# Billing Source: https://tale.dev/docs/cloud/billing Billing on Cloud is metered, not seat-based. You pay for tokens consumed by chats and agents, voice minutes, image generations, and storage; the platform itself comes with the org. This page walks one invoice line, lists the metered components, and points at the budget controls that prevent surprises. The invoice arrives monthly via email and is also visible inside the product under **Settings > Billing**. Cloud bills in your org's billing currency, which defaults to USD on sign-up and can be changed before the first invoice cuts. ## A worked invoice line A line on the invoice reads `Models — Anthropic Claude Sonnet — 1.2M tokens — $4.32`. Tale assembled it from the per-message usage ledger: every chat reply records the model used, the token count, and the cost at the rate active when the call completed. Lines aggregate by provider and model per billing period. The detail is downloadable as CSV from the same screen. ## Plan tiers Tale ships two tiers — **Community** and **Enterprise**. Community is the self-hosted open-source edition; you run it on your own infrastructure and the billing concept on this page does not apply. **Enterprise** is the managed tier (Cloud or self-hosted) with a support SLA, audit-log retention controls, SSO, the DPA, and access to regions beyond the default. The tier affects fixed monthly fees and feature gates, not per-call costs; the metered pricing for tokens, voice, and storage below applies to Enterprise on Cloud. ## Metered components | Component | Unit | Counted as | Where to view | | ----------- | ----------------- | --------------------------------------------------------- | ------------------------------------------------------------- | | Models | Tokens (in + out) | Per provider call; markup applied on top of provider rate | [Usage analytics](/platform/admin/governance/usage-analytics) | | Voice (TTS) | Characters spoken | Per agent reply rendered as audio | Usage analytics | | Voice (STT) | Audio seconds | Per user message recorded | Usage analytics | | Images | Generations | Per image returned by the model | Usage analytics | | Storage | GB-month | Object store usage averaged over the period | Billing page | ## Budgets and overages Set budgets under [Policies and limits](/platform/admin/governance/policies-and-limits). A **Budget rule** caps monthly spend per user, per team, per role, or per org. Hitting a budget reads as a clear toast — **Usage limit reached** — and pauses the affected scope until the budget is raised or the period rolls over. The default precedence is `user > team > role > default` — the most specific rule wins. A **Warning threshold (%)** on the same rule emits a notification when usage crosses the threshold without blocking. Reach for the warning when you want to know but not interrupt; reach for hard limits when overruns are an emergency. ## Where to find usage The richest view is [Usage analytics](/platform/admin/governance/usage-analytics) under Governance — it breaks usage down by **Top Assistants**, **Top Models**, **Top Voice Models**, and **Per-User Usage**, all filterable by date range. The Billing page in Settings shows the invoice-level view; Usage analytics shows the operational view. ## Where this fits Billing is the operator's headline page; [Usage analytics](/platform/admin/governance/usage-analytics) is the everyday one. If your org's cost is mostly tokens, the page worth bookmarking is the Top Models table — it surfaces which models the team has settled on and tells you whether a switch to a cheaper alternative would matter. For self-hosted users, the billing concept does not apply (you pay your provider directly); the cost-visibility page does. # Data residency Source: https://tale.dev/docs/cloud/data-residency Data residency on Cloud answers two questions every audit eventually asks: which region holds your data at rest, and which external systems touch it in flight. This page traces a single chat round-trip end to end, lists the data classes, and names every sub-processor your messages pass through. The default region for new Cloud orgs is Switzerland. Switching region after sign-up is a migration, not a setting flip — re-creating an org in the EU region is faster than moving an existing one. Pick once; pick deliberately. ## A worked example — one chat round-trip The user in Zürich opens Chat and sends "summarise the latest customer call". The request hits Tale's edge in the chosen region, lands on `tale-platform`, which calls into `tale-convex` (the backend), reads the bound knowledge from the knowledge corpus database, and emits an outbound call to the model provider the agent is configured against. Knowledge retrieval runs inside the Convex backend — it queries the corpus database directly, with no separate retrieval service in the path. The model provider returns tokens; Tale streams them back across the same path. The reply and citations land in the operational database, the corpus stays in the knowledge database, and both are replicated within the region. Two arrows cross the regional boundary in this trip: the call to the model provider (always external) and any sub-processor the agent's tools triggered (web fetch, OneDrive read, MCP server in another region). Everything else stays in region. ## Primary regions | Region | Postgres | Object store | DR replica | | -------------- | --------- | ------------ | ---------- | | Switzerland | Zürich | Zürich | Geneva | | European Union | Frankfurt | Frankfurt | Dublin | The DR replica is for disaster recovery, not active traffic. A region's data never flows to the other region's primary or replica. ## What stays in region, what leaves | Data type | Region-locked | Crosses | Notes | | ---------------------------------- | ------------- | ------- | ------------------------------------------------------------------------------ | | Chats and messages | ✓ | | | | Documents and knowledge embeddings | ✓ | | | | Org configuration and roles | ✓ | | | | Audit logs | ✓ | | | | Model provider requests | | ✓ | Goes to the provider you configured; pick a regional endpoint when one exists. | | OneDrive sync | | ✓ | Microsoft's storage region applies. | | Web tool fetches | | ✓ | Wherever the URL resolves. | ## Backups and DR Tale snapshots both Postgres databases — the operational store and the knowledge corpus — daily, and the object store hourly. Snapshots are encrypted at rest with keys held by Tale; the DR replica receives a copy within the region. Restores from snapshot are a customer-initiated operation routed through support; the SLA covers restore time. ## Changing region A region change is implemented as an export from the current region, an import into the new region, and a DNS cutover. The procedure is the same as [Migrate to self-hosted](/cloud/migrate-to-self-hosted) except both sides are Cloud regions; expect downtime in the minutes range and a planned window. There is no in-place region toggle. ## Where this fits Data residency is the first page every compliance review reads. Pair it with [Trust and compliance](/cloud/trust-and-compliance) (which framework covers what) and [Subprocessors](/legal/subprocessors) (the list of every external system named above). If your org is considering self-hosted because of a residency requirement, [Self-hosted overview](/self-hosted/overview) is the next read — running the stack on your hardware moves every arrow on this page inside your own boundary. # Cloud Source: https://tale.dev/docs/cloud Tale Cloud is the managed edition. Tale operates the infrastructure, your data is pinned to Switzerland or the EU, and your team's only operational concern is using the product. The codebase is identical to self-hosted; the difference is who keeps it running. This section covers the concerns specific to running on Cloud — onboarding, regions and data residency, billing, the trust posture you can hand an auditor, and how to migrate to self-hosted if your needs change. Every other feature reference lives one tab over under Platform, identical regardless of edition. ## Pages in this section Request your instance, create the org, configure the first model provider, publish your first agent. About an hour for an Editor. Where your data lives, which sub-processors touch it, and what changes when you switch region. Plans, seats, metered components, budgets, and where to find the invoice. The certifications Tale ships with, the shared-responsibility split, and what evidence you can hand an auditor. Export from Cloud, stand up a self-hosted instance, import. ## Where this fits Cloud is the convenient front door; Platform is where the real work lives. Once your org is signed in and the first agent is running, your team spends nearly all their time in Platform pages, not here. The one page worth re-reading whenever your operational posture changes is [Data residency](/cloud/data-residency) — it surfaces every external system your data crosses. # Migrate to self-hosted Source: https://tale.dev/docs/cloud/migrate-to-self-hosted Migration from Cloud to self-hosted is a real procedure, not a setting flip. The data exports, the new instance imports, DNS cuts over to the new host, and your team signs in to the same org they had — same agents, same chats, same audit history. This tutorial walks the procedure and points at where it goes wrong. Reach for it when self-hosting genuinely fits better: data residency requires hardware you control, costs at scale make on-premise cheaper than per-token, or the org has decided to run the stack themselves. For most teams Cloud stays the right call — re-read [Cloud onboarding](/cloud/onboarding) if you are still deciding. ## Before you begin Have these in place before exporting anything: - A target host that meets the self-hosted prerequisites — see [Quickstart](/self-hosted/install/quickstart) for the spec. - DNS control over the domain your org currently uses; you will swing it during the cutover. - A maintenance window of at least an hour. The import itself is faster than that, but DNS propagation and validation add time. - A recent backup confirmation in your Cloud org's audit log. Nothing gets deleted in the source during a migration, but the export bundle is your evidence that the source state was consistent. ## What moves and what does not Moves: chats, threads, messages, attachments, documents, knowledge embeddings, agents, agent versions, workflows, executions, audit logs, members, roles, teams, branding, API keys, integrations metadata. Does not move: external integrations have to be re-authenticated against the new instance (the credentials live in the provider, not in the export bundle); active running workflows pause and resume on the new instance after the cutover; voice audio retained past the org's retention window stays in the Cloud object store until purged. ## Step 1 — Export Open **Settings > Organization** on Cloud and click **Export**. The dialog runs the export in the background and emails a download link when complete. The export is a single encrypted bundle; the email contains the decryption key. Download the bundle and store the key separately. ## Step 2 — Stand up the target instance On the target host, follow [Quickstart](/self-hosted/install/quickstart) through the first-admin step. Do not invite users yet — the import overwrites the member list. Confirm the new instance boots and you can sign in as Owner. ## Step 3 — Import On the target instance, sign in as Owner and visit `/_internal/import` (linked from the Settings page after a fresh install). Upload the bundle, paste the decryption key, and click **Import**. The import is a long-running operation; the page shows progress per data class. When the page resolves to **Import complete**, the new instance carries the source org's full state. ## Step 4 — Cut DNS Update the DNS record for the org's domain to point at the new instance. Once propagation lands and the new instance's TLS is healthy, users signing in arrive at the self-hosted instance with their existing credentials. The Cloud org becomes read-only at this point — to avoid drift, archive it in **Settings > Organization** on Cloud after a few days of confidence. ## Troubleshooting - **Export hangs at "preparing".** Very large orgs (>100 GB) take longer than the email window assumes. Open a support ticket; the export runs to completion in the background. - **Import fails on schema mismatch.** Your target instance is running an older Tale version than the Cloud export expects. Upgrade the target before retrying — the bundle is forward-compatible, not backward-compatible. - **Members cannot sign in after cutover.** Session cookies are scoped to the old host. Members re-authenticate once; SSO and 2FA settings carry across. - **Workflows show "paused" after import.** Expected — the import preserves state but does not auto-resume running executions. Open each workflow and click **Resume** after confirming the target instance is reachable from any external triggers. ## Where this gets used Migration is a one-direction operation in practice — once you self-host, you stay self-hosted unless something changes structurally. The reverse migration (self-hosted to Cloud) follows the same shape with the same tooling and is supported but rare. If you are still on Cloud and reading this for context, the page worth following up with is [Self-hosted overview](/self-hosted/overview); it names what you are taking on. # Cloud onboarding Source: https://tale.dev/docs/cloud/onboarding This journey walks from demo request to a production-ready Cloud org with one working agent. The result is an org where your team can sign in, pick a working agent, and ask it something useful — nothing fancy yet, just the foundation everything else builds on. You need a working email address and the ability to verify it. The walk assumes no prior Tale knowledge; if anything below references a concept you have not met, the linked page introduces it. Once your instance is ready, the hands-on part takes under an hour — about half of it in the provider step, the rest mostly clicks. ## Before you begin Pin down three things: - An email address for the first Owner of the org. This account will hold the highest role; pick someone who will not leave the team next week. - API credentials for at least one model provider (OpenAI, Anthropic, Azure, or a compatible local). The provider's portal shows where these live. - The region you want your data pinned to. Cloud offers Switzerland and the EU; the choice is part of the instance setup, and switching later is a real migration. ## From demo request to a working agent Tale Cloud is not self-serve — every Cloud org runs on its own instance, set up for you by the Tale team. Fill in the demo request form at [tale.dev/request-demo](https://tale.dev/request-demo); name and email are enough, though your company and a line on what your agents should do help the team tailor the setup. The team then sets up your own demo instance — a dedicated environment, not a shared trial — and gets back to you when it is ready. Open your instance and sign up. The form asks for your name, email, and a password; verify the email link when it arrives. The next screen asks for the **Organization name** — the display name your team will see in the corner of every page. Pick something that survives a rebrand. ![The create-organization wizard on its workspace step, with Northlight Labs typed into the Organization name field and the Next button enabled.](/images/get-started/org-create-wizard.webp) The first user becomes the org's **Owner** automatically. You can see your role in the **Members** section under **Settings > Organization** later if you forget. Open **Settings > Organization**, scroll to the **Members** section, and click **Add member**. Enter the admin's name and email, assign the **Admin** role, and set a password — Tale creates the account directly and shows the sign-in credentials once, so save them and relay them to the new admin out of band (there is no invite email). They land in the org with the role you assigned. The "at least 2 Admins" safety rule means an org cannot accidentally lock itself out by removing its only Admin — add a second admin before doing anything that requires it. For the role matrix (who can do what), see [Members and roles](/platform/admin/members-and-roles). Open **Settings > AI providers** and click **Add provider**. Pick the provider you have credentials for and paste the API key. Save. Tale validates the key in the background; a confirmation on the provider row means the key works. If validation fails, the row shows the error verbatim — the most common cause is whitespace around the key. ![The AI providers settings page listing one connected provider, OpenRouter, with its base URL and a count of 52 models.](/images/get-started/settings-providers.webp) This step is where most onboarding sessions stall — the provider portal is usually a different login, and the team has to dig for the key. If validation hangs for more than a minute, refresh the page; the key is saved as soon as **Save** confirms — the row sometimes needs a reload to show it. Open **Agents** and click **Create agent**. Pick the model you just added. Write a one-paragraph instructions block — the voice the agent should answer in, the domain it knows, the cases it refuses. Save. Flip **Visible in chat** on. The agent is now reachable from any chat in the org. For a deeper walk on what makes an agent good, see [Create an agent](/platform/agents/create). Click **New chat** in the sidebar. Pick the agent from the picker, type a question the agent's domain covers, send. The reply streams back — if it lands the way you wrote the instructions to land, the org is done with onboarding. Three follow-ups worth doing now while everything is fresh: - Open **Settings > Branding** and upload the org logo. - Set the org's default language under **Settings > Organization**. - Skim [Trust and compliance](/cloud/trust-and-compliance) so you know what to show an auditor before one asks. ## Troubleshooting - **Invite email never arrives.** Check the invitee's spam folder. Tale sends from `noreply@tale.dev`; some corporate filters quarantine it. - **Provider validation fails with "invalid key".** Re-copy the key from the provider portal — copying often grabs a leading or trailing space. - **Agent does not show in the chat picker.** Confirm **Visible in chat** is on for the agent. ## Where this gets used You now have an org with one working agent and one admin besides yourself. The natural next walk is [Build your first agent end to end](/tutorials/editor/first-agent-end-to-end) — same shape, but builds an agent that does real domain work with knowledge bindings. If you came here to evaluate Cloud against self-hosted, [Migrate to self-hosted](/cloud/migrate-to-self-hosted) is the reverse walk. # Trust and compliance Source: https://tale.dev/docs/cloud/trust-and-compliance Trust and compliance on Cloud is the page an auditor wants. It names the frameworks the platform is certified against, splits responsibilities between Tale and your org cleanly, lists the data-protection controls available to you, and tells you who to call when something goes wrong. The content here is descriptive — what is shipped today, what evidence Tale can hand over on request. The legal documents themselves (DPA, terms, privacy) live under [Legal](/legal/privacy); this page is the operator's quick reference. ## A worked control — audit logs end to end The org's compliance officer needs to demonstrate that "every change to access control is logged with the actor, the target, and the timestamp". Tale's [Audit logs](/platform/admin/governance/audit-logs) record every member invite, role change, removal, and 2FA reset with the actor's user ID, the affected member's ID, and an ISO timestamp. Logs are immutable — restoring a snapshot does not modify them — and retained per the org's configured floor. The officer exports a date range as CSV, hands it to the auditor, and the worked example clears the control. ## Certifications and frameworks Tale Cloud is currently audited or attested against the following frameworks; the certification reports are available under NDA via support: - SOC 2 Type II (annual) - ISO/IEC 27001 - GDPR-aligned controls (EDPB guidance applied) - FADP-aligned controls for the Switzerland region (revDSG) Pending or planned: HIPAA BAA (US enterprise customers), additional regional attestations as the region list grows. ## Shared-responsibility split | Control | Tale | You | Evidence | | ----------------------------- | ----------------- | ---------------------- | -------------------------------------------------------- | | Infrastructure availability | ✓ | | Status page, SOC 2 SLA report | | Data encryption at rest | ✓ | | Architecture description | | Encryption in transit | ✓ | | TLS termination by Tale's edge | | Member identity and roles | | ✓ | [Members and roles](/platform/admin/members-and-roles) | | API key issuance and rotation | | ✓ | [API keys](/platform/admin/api-keys) | | Content filtering and DLP | Provides hooks | Configures rules | [Guardrails](/platform/admin/governance/guardrails) | | Audit-log retention | Provides storage | Sets retention | [Retention](/self-hosted/configuration/retention) | | Data-subject requests | Provides workflow | Initiates and approves | [DSRs](/platform/admin/governance/data-subject-requests) | | Provider credentials | | ✓ | [Providers](/platform/admin/providers) | ## Data protection controls Inside the product, three control surfaces matter for compliance: - **Audit logs** — immutable record of who did what; retention configurable. - **Legal hold** — exempts a record set from retention until lifted; covered in [Legal hold](/platform/admin/governance/legal-hold). - **Data subject requests** — the request → claim → erasure → audit workflow; covered in [DSRs](/platform/admin/governance/data-subject-requests). ## Reporting incidents Tale's security incident contact is `security@tale.dev`. Suspected vulnerability disclosure follows the responsible-disclosure policy on the same email. Customer-facing security advisories are published on the status page and emailed to the org's Owner. ## Where this fits Trust and compliance is the audit-time page; [Data residency](/cloud/data-residency) is the architecture-time page; [Subprocessors](/legal/subprocessors) is the list-of-vendors page. An auditor usually wants all three at once — bookmark them together. If you operate self-hosted, the controls are the same; what changes is who runs the infrastructure beneath them — see [Self-hosted overview](/self-hosted/overview). # AI-assisted development Source: https://tale.dev/docs/develop/ai-assisted-development Tale projects are JSON — agents, workflows, integrations, branding — and JSON edits well in AI editors when the editor knows the schema. The CLI emits two things for that: a rules file each editor reads at the project root (`CLAUDE.md` for Claude Code, `.cursor/rules/tale.mdc` for Cursor, `.github/copilot-instructions.md` for Copilot, `.windsurfrules` for Windsurf), and a read-only schema mirror under `.tale/reference/` the rules file points the editor at. Read this when you want to edit a Tale project in an AI editor without hand-typing JSON. Come back when the editor invents fields or wires the wrong agent shape — the answer is almost always that the schema under `.tale/reference/` is stale. ## A worked setup Initialise a project — the CLI writes the rules file and the schema mirror in the same step: ```bash tale init my-org cd my-org ls -a # .cursor/ .github/ .tale/ .windsurfrules # CLAUDE.md agents/ workflows/ integrations/ branding/ ``` `CLAUDE.md` (also installed as the Cursor `.mdc`, the Copilot `.md`, and the Windsurf rules file) tells the editor where to look before editing a config: > Before creating or editing any config, read the relevant schemas and implementation code in `.tale/reference/` to understand the valid structure, fields, and constraints. Use existing config files in the project as examples. The directive matters because every editor under load skips schema reads unless told otherwise. The rules file is the contract; the schema mirror is the ground truth. ## What lives where | Path | What it is | | ---------------------------------- | ----------------------------------------------------------------------- | | `agents/` | One JSON file per agent — instructions, knowledge, tools, model. | | `workflows/` | Workflow JSON configs, grouped by category subdirectory. | | `integrations//config.json` | Integration manifest — operations, auth method, allowed hosts. | | `integrations//connector.ts` | Optional TypeScript connector for REST shapes the manifest can't cover. | | `branding/branding.json` | Org branding — colours, logos, email senders. | | `.tale/reference/` | Read-only schema mirror; regenerated by `tale init` and `tale update`. | The reference tree is bytes-identical to the schemas the platform validates against at deploy time. Treat it as canonical: when a field name in a hand-written config disagrees with the reference, the reference wins. ## Working with the editor The rules file names three rules each editor enforces while editing: - **Agents bind, delegate, attach.** An agent can simultaneously bind integrations (`integrationBindings`), delegate to other agents (`delegates`), and attach workflows (`workflows`). Read existing configs before introducing a new binding. - **Workflows use integration operations.** A workflow step references integration operations declared in `integrations//config.json`. Editing a step against an operation that does not exist will fail validation. - **Naming is enforced.** Agent filenames match `[a-z0-9][a-z0-9_-]*\.json`. Workflow step slugs match `[a-z0-9][a-z0-9_-]*`. Integration directories are lowercase alphanumeric with hyphens or underscores. When the editor proposes a change, ask it to cite the file in `.tale/reference/` it relied on. If it cannot, regenerate the mirror with `tale update` and try again. ## Cursor: config plane vs runtime plane Cursor shows up in Tale in two separate places — do not conflate them. | Plane | What it does | Where it lives | | ----------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | **Config** | Helps Cursor (or any AI editor) edit Tale project JSON on your machine | `.cursor/rules/tale.mdc`, `CLAUDE.md`, `.tale/reference/` — everything `tale init` writes | | **Runtime** | Runs the Cursor Agent CLI headlessly inside an isolated sandbox when you chat with the built-in **Cursor** external agent | Chat picker → **Cursor**; agent JSON with `primaryBehavior: "external-agent"` and `agentKind: "cursor"` | The rules file and schema mirror on this page are the **config plane**: they steer a local editor while you change agents, workflows, and integrations. The **runtime plane** is a managed sandbox turn — `agent -p --output-format stream-json` with your `CURSOR_API_KEY`, normalized progress in chat, and session resume across follow-ups. Credentials, models, and billing for runtime turns are covered in [External agents](/platform/agents/external-agent), not here. ## Where this fits AI-assisted development is the editing path; deployment is the publishing path. Once a config passes editor validation, [`tale deploy`](/self-hosted/install/cli-install) reconciles it against the platform — the same schema check, this time as a gate. For features the editor cannot reach (the in-product builder, the visual workflow editor), the [Platform tab](/platform) is the canonical surface; the AI-editor path here is for projects that prefer config-as-code. # API reference Source: https://tale.dev/docs/develop/api-reference The Tale API is the surface integrators use when they are outside the product and want to script it. Authentication is an API key in a header; the data plane is JSON over HTTPS; a subset of the chat endpoints speaks the OpenAI Chat Completions format so existing OpenAI client libraries work unchanged. This page is the canonical inventory of the API surface, the auth model, and the error shape. It does not enumerate every payload field — that lives next to each endpoint group in the linked sub-pages. Read this before you call the API; come back when you are not sure which header carries the key or what a 429 means. ## A worked request The shortest useful request — list the agents your key can see — is one curl: ```bash curl -sS https://your-host.example.com/api/v1/agents \ -H "Authorization: Bearer $TALE_API_KEY" \ -H "Accept: application/json" ``` A successful response is JSON: `{ "agents": [ { "id": "...", "name": "...", "visibleInChat": true, ... }, ... ] }`. Every list endpoint returns the same shape — a top-level object with one array property named after the resource. ## Authentication API keys are minted in the UI under **Settings > API keys** by anyone with the Developer role or above. Each key has a name, an owner, and a scope; the scope follows the role of the issuing user at the time of creation. Keys are shown once at creation; Tale never displays the raw key again. Pass the key as a bearer token: `Authorization: Bearer `. The key authenticates the request; the org context is inferred from the key. A key cannot be used outside its issuing org. Cookies authenticate the browser session; API calls from the browser inside the product use cookies. Server-side scripts use the API key. ## Endpoint groups | Group | Method | Path | Auth required | Notes | | -------------------------------------------------- | ------- | ---------------------------- | ------------- | -------------------------------------------------- | | Agents | various | `/api/v1/agents/...` | API key | List, get, run. | | Chat | various | `/api/v1/chat/...` | API key | Stream chat completions against an agent or model. | | OpenAI-compatible | POST | `/api/v1/chat/completions` | API key | OpenAI Chat Completions shape; use existing SDKs. | | OpenAI-compatible | POST | `/api/v1/images/generations` | API key | Generate images; OpenAI Images shape. | | OpenAI-compatible | GET | `/api/v1/models` | API key | List available models in OpenAI format. | | Workflows | various | `/api/v1/workflows/...` | API key | Run by slug, schedules, webhooks, executions. | | Workflow webhooks | POST | `/api/workflows/wh/` | URL token | Fire a webhook-triggered workflow from outside. | | Knowledge — Documents | various | `/api/v1/documents/...` | API key | Upload, list, get, delete. | | Knowledge — Customers, Products, Vendors, Websites | various | `/api/v1//...` | API key | List, get, create, update. | | Conversations | various | `/api/v1/conversations/...` | API key | List by status, get, write messages. | | Files | various | `/api/v1/files/...` | API key | Upload, get, delete. Used by uploads. | Exact field shapes for each endpoint live in the OpenAPI document the platform emits at build time; load it in a Swagger or Stoplight viewer to see request and response schemas with examples. The endpoint groups in the table above are the high-level inventory; the OpenAPI doc is the field-level reference. ## OpenAI-compatible endpoints `POST /api/v1/chat/completions` accepts a payload in OpenAI Chat Completions shape and returns a streaming or non-streaming response in the same shape. The `model` field is interpreted as the agent ID — pass an agent's ID to route through that agent's instructions, knowledge, and tools. Pass a raw model name (e.g. `gpt-4o`) to bypass agents and call the provider directly. Existing OpenAI SDKs work with one change: point the base URL at `https://your-host.example.com/api/v1` and substitute the API key. Streaming uses Server-Sent Events. ### Vision To send an image, give the user message an array `content` of parts instead of a string — a `text` part plus one or more `image_url` parts, each carrying a `data:` URL or a public `https` URL. This is the standard OpenAI vision shape, so an SDK that already builds multimodal messages needs no change. A plain string `content` still works for text-only turns; only image input requires the array form. ### Image generation `POST /api/v1/images/generations` takes `{ model, prompt, n?, response_format? }` and returns the OpenAI Images shape — `{ created, data: [...] }`. `response_format` is `url` (the default — each entry is a download URL) or `b64_json` (each entry is base64 image bytes); `n` is capped at 4. Call it through any OpenAI SDK's `images.generate`. Passing an image-generation model to `/api/v1/chat/completions` works too: the generated image comes back on the assistant message as `choices[0].message.images[]` — each an `image_url` — matching the convention image-capable gateways use, so the call is billed against a returned image rather than a dropped one. To edit an existing image, send that same request with a `text` part and an `image_url` part carrying a `data:` URL to a model that supports editing; the edited image returns the same way. Only `data:` URLs are read as edit inputs — Tale never fetches an `http` image URL server-side. ## Error model Errors land as JSON: `{ "error": { "code": "", "message": "", "details"?: { ... } } }`. The HTTP status is one of: - **400** — malformed request (missing field, wrong type). - **401** — missing or invalid API key. - **403** — the key is valid but does not have the role required for the action. - **404** — the resource does not exist or the key cannot see it. - **409** — conflict (e.g. duplicate idempotency key with different body). - **422** — semantically invalid (e.g. agent referenced for a workflow trigger has been archived). - **429** — rate limit hit. See [Rate limits](/develop/rate-limits). - **500** — internal error. The body's `details` field has a request ID you can quote in support. The `code` is a symbol (`unauthorized`, `forbidden`, `agent_not_found`, …); the `message` is human-readable. Clients should branch on `code`, not on the human message. ## Idempotency Every write endpoint accepts an `Idempotency-Key` header. The first request with a given key succeeds; subsequent requests with the same key return the same response without re-executing. The key is valid for 24 hours. Idempotency is required for webhook-trigger calls — the source system must send a stable key per logical event so retries do not double-fire the workflow. ## Versioning The API is versioned by URL prefix: today, `/api/v1/`. Breaking changes ship under a new prefix; the old prefix stays available for at least one minor version. Non-breaking additions land in the current prefix. The release notes name the API version each release ships against; pin your client library to the current version when in production. ## Where this fits The API is the seam between Tale and everything outside it. Webhooks are the other half — for events Tale needs to push to you, or for you to push at Tale's workflows, the [Webhooks reference](/develop/webhooks) covers the signing and idempotency rules. If you are building inside the product as a Developer-role user — agents, workflows, custom tools — the [Platform tab](/platform) is your day-to-day; this page is for outside. # Contributor setup Source: https://tale.dev/docs/develop/contributor-setup This page is for contributors who want to run Tale from source and ship a change back. It covers the prerequisites, the one-time setup, the pre-flight check that catches a broken machine before a long boot, and what to expect from `bun run dev`. It is not the operator path — if you want to run Tale to use it, not change it, the [self-hosted quickstart](/self-hosted/install/quickstart) installs the packaged stack with the CLI instead. The source is one Bun workspace, end to end — the whole stack is TypeScript, with no Python and no second package manager to install. A single `bun install` wires up every service, and `bun run dev` boots the platform with a local Convex backend, generated dev secrets, and Vite — no cloud account, no hand-edited `.env`. Knowledge work that used to live in standalone services (RAG search, document ingestion, web crawling, document generation) now runs inside the Convex backend, so there is nothing extra to start for it. ## A working setup, start to finish The shortest path from a fresh clone to a running app is four commands. The pre-flight check between install and dev is the one that saves you a confusing failure ten layers deep: ```bash bun install # wire up every workspace bun run setup:check # validate Bun, the dev ports, and the Convex CLI bun run dev # boot Convex + Vite (watch for the READY banner) ``` If `setup:check` prints all green and `bun run dev` reaches its `READY` banner, your environment is sound. The rest of this page explains each piece and what to do when one of them complains. ## Prerequisites Only one tool has to be on your `PATH` before anything else, because the whole stack is TypeScript on a single runtime: - **Bun 1.3 or higher** — the workspace runtime and package manager. Install it from [bun.sh](https://bun.sh/docs/installation), then confirm with `bun --version`. Everything else the source needs (the Convex CLI, every service dependency) is resolved by `bun install`. You do not need Docker for local development with `bun run dev` — it spawns Convex directly on your machine. Docker only enters the picture for the containerised hybrid mode below and for the operator install. ## Install and pre-flight A single install covers every workspace, because the repo is one Bun workspace graph: ```bash bun install ``` Before the first `bun run dev`, run the pre-flight check. It validates your Bun version, that ports 3000 and 3210 are free, and that the Convex CLI is reachable — and prints the exact fix for anything missing, so you do not discover a wrong Bun version halfway through a cold boot: ```bash bun run setup:check ``` Each failing line carries its remediation: a `bun upgrade` for an old Bun, an `lsof`/`kill` pair for a busy port. A clean run exits zero and tells you to go ahead with `bun run dev`. ## What `bun run dev` does `bun run dev` is the development orchestrator. It loads your `.env` files, generates insecure local defaults for any secret you have not set, spawns a local Convex backend in anonymous mode, syncs the environment into it, runs Convex codegen, waits for the auth routes to answer, then starts Vite. The platform is the slowest server to come up because it waits on Convex, so a cold start takes 30 to 90 seconds. Until the orchestrator prints its `READY` banner, the app refusing connections on `http://localhost:3000` is expected, not a failure — Vite has not bound the port yet. When you see the banner, the app is reachable and auth is healthy. Stop the whole stack with `Ctrl-C`; it shuts down both Convex and Vite cleanly. The dev orchestrator generates everything it needs, so a local `.env.example` copy is optional for local development — the insecure defaults (`INSTANCE_SECRET`, `BETTER_AUTH_SECRET`, the WebDAV HMAC key) are filled in at boot and printed as warnings. Set real values in `services/platform/.env.local` only when you need production-shaped behaviour or want to override a default. ## When a port is busy `bun run dev` binds two ports: 3000 for the Vite app and 3210 for the local Convex backend. It fails fast with an actionable message when either is taken, because a silent fallback to another port would break the Convex proxy and every `localhost:3000` link. The usual culprit is a previous `bun run dev` or `tale dev` that did not fully exit. Free the port and re-run. The command that finds and stops the holder is the same one `setup:check` and the orchestrator suggest: ```bash lsof -nP -iTCP:3000 -sTCP:LISTEN # show the PID holding the app port kill # stop it ``` To run the app on a different port instead, set `PORT`: `PORT=3005 bun run dev`. If the Convex deployment itself gets into a bad state after automatic maintenance — a stale schema after an aborted migration, a corrupt local SQLite file — see [Resetting local Convex dev data](#resetting-local-convex-dev-data) below; do not delete `.convex/local/` casually. ## Convex local storage maintenance Every `convex dev` push stores a new function-bundle blob under `services/platform/.convex/local/default/convex_local_storage/modules/`. The Convex CLI never garbage-collects old blobs locally, so months of daily dev can accumulate tens of thousands of files (10+ GB) and make cold starts fail inside the CLI's 30-second backend-ready window. `bun run dev` runs maintenance automatically before it spawns Convex: - **Prune** when module storage exceeds 1,500 blobs or 2 GB — deletes only unreferenced historical function-bundle blobs under `convex_local_storage/modules/`, keeping every blob the current deployment still loads (module source packages and their node `externalPackageId` deps parents, plus up to 1,000 newest unreferenced leftovers). Your SQLite database, uploaded files, and org config are untouched. If the deployment's live references can't be read, or look empty while blobs remain on disk, prune is skipped rather than guessing. - **Integrity gate** — if a live module blob is already missing on disk, `bun run dev` stops with a clear error pointing at `setup:clean`. Continuing would boot into a half-dead backend (chat and crons fail with opaque server errors). - **Clear snapshot export artifacts** when the cached Convex backend binary no longer matches the one recorded in your local deployment — removes `export.zip` and related import/export debris that can trigger a failed re-import on cold start, without wiping dev data. Set `TALE_DEV_SKIP_CONVEX_MAINTENANCE=1` to opt out of prune/snapshot cleanup (the integrity gate still runs). `bun run setup:check` warns (non-blocking) when module storage is already over the prune threshold. ## Resetting local Convex dev data Last resort only — `bun run setup:clean` wipes **all** local Convex dev data: every table in the local SQLite file, every upload in `convex_local_storage/files/`, and every function bundle. Org config on disk and `.env.local` are untouched. **Keep your data across the reset.** Even when the integrity gate fires (a live module bundle is missing), the backend itself still starts — so you can export your data first and restore it afterwards, and the reset then loses nothing: ```bash # 1. Start the backend (this bypasses the `bun run dev` integrity gate), then # export in a second terminal: bun run --filter @tale/platform convex:dev cd services/platform && npx convex export --path convex-backup.zip # 2. Reset (guarded — see below), bootstrap a fresh deployment, then restore: bun run setup:clean # type: delete local convex bun run dev # wait for the READY banner cd services/platform && npx convex import --replace-all convex-backup.zip ``` `bun run setup:clean` is guarded on purpose (coding agents must not run it unless you explicitly asked): 1. Run it yourself in a terminal — not through an agent. 2. When prompted, type the exact phrase `delete local convex` (a bare `y` is rejected). 3. Non-interactive runs (CI) require `TALE_CONFIRM_DESTROY_LOCAL_CONVEX=delete-local-convex` — never set that in agent shells. Try automatic maintenance and a normal `bun run dev` first. If you must reset, **export first** (above) to keep your data — only skip the export when you truly don't need the local conversations, uploads, and other anonymous-deployment state. ## Hybrid mode against a containerised Convex `bun run dev` spawns an ephemeral Convex backend by default, which is the right thing for most work. When you want fast Vite reloads against a stable Convex that mirrors production, run the dedicated `convex` container and point Vite at it instead: ```bash docker compose up convex # one terminal: the stable backend CONVEX_EXTERNAL=true bun run dev # another: Vite against the container ``` Set `CONVEX_URL` if your container exposes Convex on a non-default host or port. This is the only local-dev path that needs Docker, and it is optional — the default ephemeral backend needs nothing beyond the three prerequisites. ## Before you open a PR Every PR runs through one gate: `bun run check`, which is format, lint, typecheck, and the full test suite across every touched workspace. A green run is the merge signal; a red one blocks. The pre-PR checklist in [`AGENTS.md`](https://github.com/tale-project/tale/blob/main/AGENTS.md) lists the rest — docs and translations ship in the same PR as the code that changed them. If your change touches `services/docs/`, also run the docs gate (`bun run --filter @tale/docs test`) so structural parity, terminology, and prose checks pass before review. Anything a user can see, configure, or call needs its docs updated in all three base locales in the same commit. ## Where this fits Contributor setup is the floor every other developer task stands on: get the prerequisites in place, let `setup:check` confirm the machine, and `bun run dev` gives you the whole platform with a local backend in under two minutes once the images are warm. The pre-flight check and the port remediation exist because the most common first-run failures are a wrong tool version or a leftover process holding a port — both are five-second fixes once you can see them. Once the stack runs, the [Develop overview](/develop/overview) frames the external surface you build against, and [AI-assisted development](/develop/ai-assisted-development) covers using Tale's own agents to author Tale configs. If you are contributing a container change rather than a source change, [Contributing](/self-hosted/contributing-docker) under the Self-hosted tab is the build-and-test walk for that path. # Integrations Source: https://tale.dev/docs/develop/integrations Integrations are the seams between Tale and the rest of your stack. The shipped catalogue covers the common SaaS systems (Slack, GitHub, Microsoft 365, Google Drive, Shopify, and the rest); when your target system is not there, you build the bridge yourself. Three surfaces let you do that: a JSON-declared REST connector, a SQL adapter for relational databases, or an MCP server when you need a self-hosted process to broker the calls. Read this when you are extending the integration catalogue. Come back when an operation you declared does not appear in the agent toolbelt — the answer is almost always a schema mismatch against the reference under `.tale/reference/integrations/`. ## A worked custom REST connector The smallest useful integration is a single REST operation declared in JSON. Drop a folder into the project and the integration appears under **Settings > Integrations** without a code change: ```text integrations/ acme-billing/ config.json connector.ts # optional, for non-trivial request shaping icon.svg ``` `config.json` declares the auth method, the allowed hosts, and the operations: ```json { "slug": "acme-billing", "name": "ACME Billing", "auth": { "type": "apiKey", "header": "X-API-Key" }, "allowedHosts": ["api.acme.example.com"], "operations": [ { "name": "list_invoices", "method": "GET", "path": "/v1/invoices", "query": { "since": "string?" } } ] } ``` The operation surfaces on agents as a tool family the moment the org connects credentials. The connector file is optional — reach for it when the response shape needs flattening or pagination loops the manifest cannot express. For an OAuth2 connector (`"auth": { "type": "oauth2", … }`), register Tale's callback URL as an allowed redirect URI in the upstream OAuth app, or the consent step fails with a `redirect_uri` mismatch. The callback is `${SITE_URL}/api/integrations/oauth2/callback` (prefixed with `BASE_PATH` when one is set). For local development that origin is your dev URL — `http://localhost:3000/api/integrations/oauth2/callback`, not an `https://` host. ## Surface choices | Surface | Reach for it when | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | REST manifest | The target system speaks JSON over HTTPS and the auth is API key or OAuth2. Covers most SaaS APIs. | | SQL adapter | The target is a relational database (Postgres, MySQL, SQL Server) and you want agents to read tables under a row-level access policy. | | MCP server | The bridge needs to be a long-lived process — local files, a CLI you own, a system that cannot be reached from Tale's network. | | Connector TS | The REST manifest covers 80 % of the API but one operation needs response shaping the manifest cannot declare. | The shipped integrations under [Platform > Integrations](/platform/integrations/overview) are the catalogue of REST manifests Tale ships — read their configs in `builtin-configs/integrations/` for the patterns you will copy. ## SQL adapters A SQL adapter exposes a Tale-shaped tool surface over a SQL database. You declare the connection (driver, host, credential ref) and the tables the integration is allowed to read; the adapter generates a `query_` operation per declared table and a `run_named_query` operation for the queries you whitelist by name. Writes go through declared mutations only — there is no raw `execute` operation. Per-row authorisation is the operator's responsibility: declare a tenant column on each table and Tale will inject the tenant filter into every generated query. Operations that touch a table without a tenant column fail validation at deploy time. ## MCP servers When the integration cannot be expressed as a JSON manifest — a CLI, a local toolchain, anything network-isolated from Tale — write an MCP server and register it under **Settings > MCP servers**. Each tool the server exposes appears in the agent toolbelt with per-tool approval the first time it is called. The transport is stdio for self-hosted Tale; for Tale Cloud, the server lives on your network and Tale calls it over a signed HTTPS tunnel. The full MCP integration walk-through lives at [MCP server from scratch](/tutorials/developer/mcp-server-from-scratch) — that page is the build; this page is the chooser. ## Where this fits Custom integrations are how Tale reaches systems the shipped catalogue does not cover. The [Integrations overview](/platform/integrations/overview) lists what is already there; once your custom integration is declared, [Agent tools](/platform/agents/tools) explains how its operations surface on an agent. If you need the bridge to live outside Tale entirely — a process you start, a host you control — the [MCP servers reference](/platform/integrations/mcp-servers) covers the other half. # Develop Source: https://tale.dev/docs/develop/overview Develop is the section for integrators and contributors — anyone wiring Tale into another system, building on top of the API, or shipping a change to the source. The pages here describe the external surface (REST, webhooks, OpenAI-compatible endpoints) and the contributor workflow. If you are inside the product as a Developer-role user (building agents, workflows, custom tools), the Platform tab covers your day to day; Develop is for when you are outside the product, talking to it across the wire. ## Pages in this section Endpoints, authentication, OpenAI-compatible endpoints, error model, versioning. Outbound (Tale → you) and inbound (you → Tale), signing, idempotency, retries. Using Tale agents to author Tale workflows, the `.agents/` skill files. Third-party integrations from a developer perspective. Cloud incident reporting, self-hosted metrics pointers. Per-key, per-IP, per-org limits and how to interpret 429s. ## Where this fits Develop is the smallest section because most users never need it; the audience is concentrated in two roles (in-product Developer, out-of-product contributor) but it is load-bearing for both. If you are wiring something external to Tale, [API reference](/develop/api-reference) is the first read; if you are contributing to the source, [Contributing](/self-hosted/contributing-docker) — under the Self-hosted tab — is. # Rate limits Source: https://tale.dev/docs/develop/rate-limits Tale's REST API is rate-limited per key and per org. The defaults are sized for normal application traffic — bursts are fine, sustained hammering returns 429. When you hit a limit, the response carries the headers you need to back off cleanly; the wrong move (retry without delay, retry forever) only deepens the throttle. Read this when you are wiring a client that calls the API on a schedule or under load. Come back when a previously healthy integration starts returning 429 — the answer is usually a missing backoff, not a missing capacity grant. ## A worked 429 The shortest useful interaction is a request that overruns its key budget. The server returns: ```http HTTP/1.1 429 Too Many Requests Content-Type: application/json Retry-After: 12 X-RateLimit-Limit: 120 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1717000060 { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 12 seconds." } } ``` `Retry-After` is the authoritative wait — sleep at least that long before the next attempt. `X-RateLimit-Reset` is the Unix timestamp at which the window refills. The body's `code` is `rate_limited`; clients should branch on the code, not parse the message. ## Default limits | Surface | Budget | Bucket | | ------------------------------- | ----------------------------- | ---------------- | | REST API (`/api/v1/*`) | 120 requests / minute / key | Token, burst 200 | | OpenAI-compatible chat | 30 requests / minute / key | Token, burst 50 | | OpenAI-compatible model listing | 120 requests / minute / key | Token, burst 200 | | Workflow trigger webhooks | 60 requests / minute / key | Token, burst 100 | | Agent webhooks | 30 requests / minute / key | Token, burst 50 | | File upload | 50 requests / minute / member | Fixed window | | Email send | 100 messages / hour / org | Token, burst 120 | Token buckets allow a short burst above the rate — useful for batch imports — then settle to the sustained rate. Fixed windows refill at the minute boundary; a request at 14:59:59 and another at 15:00:00 both pass. Pick the buckets to match: a UI mounting once a minute reads as one token, not 60 over a window. ## Per-org caps Tale Cloud applies a soft per-org cap on top of the per-key budgets, scaled to the org's plan. The cap protects against a runaway key by making sure one client cannot consume the org's entire budget. Self-hosted instances have no per-org cap by default — the per-key budgets above are the only floor. When you need a higher per-key budget for a known workload on Cloud, ask support with the key name and the expected sustained rate. Capacity grants are per key, not per org. ## Retry strategy The right strategy is exponential backoff with jitter, capped at the `Retry-After` value when present: 1. On 429, read `Retry-After` and sleep at least that long. 2. If `Retry-After` is absent (unusual), start at 1 s and double on each subsequent 429, capped at 60 s. 3. Add up to 25 % jitter so concurrent clients do not retry in lock-step. 4. Give up after the eighth attempt and surface the failure — the bucket is saturated and retrying further will not help. Idempotency matters here: every write endpoint accepts an `Idempotency-Key` header. Set a stable key per logical operation so retries do not double-fire when the original request succeeded but the response was lost. See [API reference](/develop/api-reference) for the idempotency window. ## Where this fits Rate limits are how Tale stays available when one client misbehaves. The [API reference](/develop/api-reference) names the 429 in the error model and points back here for the rules; the [Webhooks reference](/develop/webhooks) covers the matching retry policy on outbound deliveries. If your traffic is shaped wrong for the defaults and a support grant is not enough, the [Self-hosted](/self-hosted/overview) tab is the other answer — running the platform on your own infrastructure removes the Cloud-imposed caps. # Status page Source: https://tale.dev/docs/develop/status-page The status page is the canonical record of Tale Cloud availability. Each rotatable service has its own status row, incident history is kept for the audit trail, and the page is the channel Tale uses during an incident — before email goes out, before support tickets are answered, the page is updated. Read this when something is misbehaving and you want to know whether it is just you. Subscribe to the feed when you are responsible for the integration on your side — the page tells you which service degraded so you can route the alert to the right team without waking the wrong on-call. ## A worked subscription The status page is at `https://status.tale.dev`. Subscribing takes one URL: ```bash curl -sS https://status.tale.dev/history.rss ``` The RSS feed carries every state change — open, update, resolved — for every service. Email subscription is the same one-click form on the page; the email channel ships the same events with a five-minute debounce. ## Scope per service | Service | What it covers | When it goes red | | ---------- | ---------------------------------------------------------------------------------- | ------------------------------------------------ | | `platform` | The TanStack Start + Convex application — agents, workflows, integrations, UI. | UI unreachable; API returns 5xx; auth broken. | | `rag` | The Python FastAPI document-processing service — indexing, retrieval. | Document uploads stall; retrieval is empty. | | `crawler` | The Crawl4AI web-extraction service — used by document ingest and Tavily fallback. | Web-pulled documents fail; deep research stalls. | | `proxy` | The Caddy edge — TLS termination, HTTP routing. | All Tale Cloud traffic affected. | | `db` | TimescaleDB — durable state for the Convex layer and platform metadata. | Writes refused; the platform row also goes red. | Each row carries the last 90 days of uptime as a sparkline. An incident reads as a coloured band on the row; clicking the band opens the timeline — first update, follow-ups, resolution, post-mortem when one is owed. ## Incident history History is kept indefinitely. Each incident records the affected services, the customer impact statement, the timeline, and the post-mortem when the incident crosses the severity threshold that obliges one. The threshold is published on the page itself; the rule of thumb is anything with cross-org customer impact and a duration above 30 minutes. The page is owned by the on-call rotation. Updates are pushed by the engineer holding the page, not by an automated system — the choice is deliberate, because the page is also the document that goes to customers and auditors after the fact. ## Self-hosted: what changes Self-hosted instances do not appear on `status.tale.dev` — that page covers Tale Cloud. Each deployment ships its own status page instead, served by the platform and reachable without signing in at `https:///status`. It renders a server-side health summary — operational, degraded, or outage — from a liveness probe against the Convex backend, so an operator (or an end user checking whether it is just them) can read availability without a login. The machine-readable form is `https:///status.json`, which returns the same result as JSON for an uptime monitor to poll. That page reports the availability of the deployment itself. For deeper operational signal — container health from `tale status`, request metrics from the Caddy logs, and control-plane events in the in-product audit log — the [observability troubleshooting page](/self-hosted/operate/observability/troubleshooting) maps symptoms to logs. ## Where this fits The status page is the operational channel; [Trust and compliance](/cloud/trust-and-compliance) is the audit channel and lists the page as evidence for the infrastructure-availability control. If you are wiring Tale into a pipeline and need the integration to react to a Tale outage, the RSS feed is the input; if you are reading this because something in your integration is failing right now, [API reference](/develop/api-reference) lists the error codes you should branch on. # WebDAV API Source: https://tale.dev/docs/develop/webdav-api Tale exposes the document store under `/dav//` as a read-write WebDAV Class 2 endpoint (RFC 4918). This page is the protocol reference — the wire-level surface a client implementer or a third-party tool needs to integrate. For the end-user setup guide and per-client instructions, see [Platform > Integrations > WebDAV](/platform/integrations/webdav). ## URL scheme ```text /dav//documents/ R/W active documents tree /dav//.trash/ R/O trashed documents (soft-delete view) /dav// R/O collection containing the two above ``` Segments are URL-encoded. The server rejects segments containing `/`, `\`, NUL, or the relative names `.` and `..`. Each segment must be 1–255 bytes. The `orgSlug` matches `[a-zA-Z0-9_-]{1,64}`. Trailing-slash policy follows WebDAV convention: collections (folders) are referenced with a trailing slash, resources (files) without. Many clients normalise on the fly; the server accepts both forms on lookup and emits the canonical form in PROPFIND responses. ## Authentication HTTP Basic only. The username field can be any non-empty value — the app-password itself is the actual credential, and the server does not match the username against your account record. Using your Tale account email is the convention for audit clarity, and clients that prefill from the keychain expect an email-shaped string, but the auth decision is made on the password alone. The password is an **app-password** generated under Settings > WebDAV. The user's main account password is not accepted on this endpoint. ```http Authorization: Basic ``` App-passwords are hashed with HMAC-SHA256 keyed by the server's `WEBDAV_APP_PASSWORD_HMAC_KEY` deployment secret. The key is derived deterministically from `INSTANCE_SECRET` by the platform entrypoint (prod) and `server.ts` (dev), so operators do not mint it manually; setting it explicitly in `.env` overrides the derived value. Lookup narrows by the password's first four characters (stored alongside the hash for indexed lookup) and verifies with a constant-time HMAC comparison. Every authenticated request also verifies the requesting user is an active member of the organisation in the URL — a stale row (membership removed after app-password issue) is rejected with `403`. `OPTIONS` is the only method allowed without authentication; clients use it to probe DAV capability before signing in. ## Methods | Method | Behaviour | Auth | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | | OPTIONS | Advertise capabilities. Returns `DAV: 1, 2`, `Allow: …`, and `Microsoft-Server-WebDAV-Extensions: 1` for Windows compatibility. | Anonymous OK | | PROPFIND | List a resource (Depth 0) or a collection's immediate children (Depth 1). The property list emitted is documented below. **Depth: infinity is rejected with 403** to prevent unbounded responses. | Required | | PROPPATCH | Returns 207 success per-property without storing values. Dead properties are not persisted in v1; PROPPATCH succeeds optimistically for client compatibility. | Required | | GET / HEAD | Stream the document blob. Sets `Content-Type`, `Content-Length`, `ETag`, and `Last-Modified`. GET on a collection returns 405. | Required | | PUT | Create or replace a document. New blob is stored in Convex storage with content-hash dedup; the document row picks up `sourceProvider: "webdav"`. Returns 201 on create, 204 on overwrite. | Required | | DELETE | Soft-delete a document (sets `lifecycleStatus: "trashed"`) or a folder (cascades trash on contained documents, hard-deletes the folder rows). Returns 204. | Required | | MKCOL | Create a folder under an existing parent. Empty body only. Returns 201, 405 if the target exists, or 409 if the parent does not. | Required | | MOVE | Rename or relocate. Atomic for documents. For folders, updates the `parentId` of the moved folder. Honours `Overwrite: T/F` and `If` headers. Returns 201 (new destination) or 204 (overwrite). | Required | | COPY | Server-side copy. Document copies reuse the same Convex storage id (dedup). Folder copies recurse. Honours `Overwrite` and `If`. | Required | | LOCK | Class 2 exclusive or shared write-lock. Timeout from `Timeout: Second-N` header, capped at 3600. Refresh by re-sending LOCK with `If: ()` and an empty body. | Required | | UNLOCK | Release a lock by its token. Only the lock owner can release. Returns 204. | Required | `HEAD` shares its handler with `GET` minus the body. ## Properties PROPFIND returns these live properties for every resource: - `resourcetype` — `` on folders, empty on documents. - `displayname` — the folder name or document title. - `getlastmodified` — RFC 1123 timestamp. Documents use `sourceModifiedAt` if set, otherwise the document row creation time. - `creationdate` — ISO 8601 of the row creation time. - `getcontenttype` — documents only; the MIME type the document was uploaded with. - `getcontentlength` — documents only; bytes. - `getetag` — documents only; the content hash if known, otherwise the document id. - `supportedlock` — advertises exclusive write-lock support. - `lockdiscovery` — present on resources with active locks. Dead properties are not stored. PROPPATCH echoes 200 for a dead property set on its own, but setting a live/protected property returns a per-property 403 (`cannot-modify-protected-property`), and any dead properties in the same request are then reported as 424 Failed Dependency (RFC 4918 §9.2 atomicity). No value is ever persisted. ## Lock semantics Locks live in their own Convex table, keyed by `(organizationId, resourcePath)`. Wire form is `opaquelocktoken:`. The server: - Caps timeout at 3600 seconds. Requests for longer windows are clamped silently. - Treats `LOCK` with an `If: ()` header and an empty body as a refresh — the existing lock's expiry is bumped. - Returns `412 Precondition Failed` on a refresh when the supplied token is unknown. - Returns `423 Locked` on `PUT / DELETE / MOVE / COPY / MKCOL / PROPPATCH` against a locked path when the request lacks a matching `If` header. - Returns `412 Precondition Failed` when the supplied `If` token does not match the live lock. - Expires locks lazily — the lookup query returns null for expired rows and schedules a fire-and-forget delete. - Hard-deletes every lock owned by an app-password when that app-password is revoked. `UNLOCK` requires both a valid `Lock-Token` header and the requesting user to be the lock owner. ## Status codes - `200` — OPTIONS, GET, HEAD, LOCK, LOCK refresh, PROPPATCH (per-property) - `201` — PUT create, MKCOL, MOVE/COPY to a new destination - `204` — DELETE, UNLOCK, PUT overwrite, MOVE/COPY overwrite - `207` — PROPFIND, PROPPATCH (multi-status envelope) - `400` — malformed `Destination` / `If` / `Lock-Token` / `Timeout` header - `401` — missing or invalid Basic auth - `403` — Depth: infinity rejected; .trash write attempt; root delete/move; wrong app-password owner on UNLOCK; user not a member of the org; MOVE/COPY onto itself or into its own subtree; cross-org `Destination` - `404` — resource not found - `405` — GET on a collection; PUT to a collection path; MKCOL on existing path; root MKCOL - `409` — MKCOL, MOVE, or COPY when the destination parent does not exist - `412` — `If` token mismatch; `If-Match` / `If-None-Match` precondition failed; MOVE/COPY with `Overwrite: F` onto an existing destination - `413` — PUT body over the size cap, or an XML request body (PROPFIND / PROPPATCH / MKCOL / LOCK) over 64 KB - `415` — MKCOL with non-empty XML body (extended MKCOL not implemented) - `423` — write attempted on a locked path without matching `If` - `502` — cross-host `Destination`; storage proxy fetch failed - `503` — LOCK count cap exceeded for the app-password (with `Retry-After`) - `507` — folder subtree too large to delete, move, or copy in a single request ## Compliance - DAV Class **1** (basic): full. - DAV Class **2** (locking): full, with the lazy-expiry behaviour described above. - DAV Class **3** (calendaring, contacts, search, ACL): not implemented. The server advertises `DAV: 1, 2` in the OPTIONS response. ## Limits - `Depth: infinity` on PROPFIND is rejected with `403`. - `Timeout: Second-N` on LOCK is clamped to `[1, 3600]`. - PUT body size is capped at **5 GB** by default (`413` once exceeded), enforced both at the reverse proxy and in the platform server. Operators can raise or lower it with the `WEBDAV_MAX_PUT_BYTES` environment variable. The body is streamed to a Convex presigned URL with backpressure, so a large upload does not buffer in platform memory. - XML request bodies (PROPFIND / PROPPATCH / MKCOL / LOCK) are capped at **64 KB** (`413` once exceeded) — these envelopes are tiny by design. - App-passwords are hashed with HMAC-SHA256; the secret never appears in any response after the create call. - `lastUsedAt` is patched at most once per minute per app-password to avoid write storms on busy mounts. ## Network requirements The WebDAV endpoint runs inside the platform Hono server (`platform:3000` in compose). Caddy routes `/dav/*` to it via the default fallback — no extra configuration is required. The path requires the platform server to have `ADMIN_KEY` set in its environment so it can call internal Convex queries with admin auth. For dev (`bun dev`), the same dispatch is mounted as a Vite middleware (`vite-plugins/serve-webdav.ts`) — `curl` and clients can hit `http://localhost:3000/dav//...` against a running dev server without rebuilding. ## Security WebDAV ships the app-password on every request as an HTTP Basic header — there is no session, no token refresh, just the raw credential replayed on every PROPFIND, PUT, LOCK, and so on. Only mount the endpoint over HTTPS; running it over plain HTTP leaks the password to anyone on the wire, and revoking the row is the only way to recover. Never put the app-password into the URL itself (the `https://user:pass@host/...` shorthand) — most clients log URLs in shell history, crash reports, and proxy access logs, where the credential would survive long after the mount was unmounted. Let the WebDAV client store the password in the OS keychain (macOS Keychain, Windows Credential Manager, GNOME Keyring) and surface it through the standard credential prompt instead. The server enforces TLS at the reverse proxy layer in production deploys; dev mode over plain HTTP is only intended for `localhost` testing. Audit logs record every authenticated request with the prefix of the password used, so a leaked credential can be traced and revoked without rotating the rest of the device fleet. ## Where this fits WebDAV is the mount-protocol surface of the same document store the [REST API reference](/develop/api-reference) drives for bulk import and search — both routes write into the table the [Document Hub](/platform/knowledge/documents) reads from, so a file created through Finder appears in the web UI without any sync step. The protocol is the right pick when a user wants their documents to feel like a local folder; the REST API is the right pick when a script or agent wants byte-level control over what gets written and when. RFC 4918 is the wire-level authority for everything on this page. # Webhooks Source: https://tale.dev/docs/develop/webhooks Webhooks are how Tale and the rest of your stack talk asynchronously. Two directions exist: inbound — your system POSTs to a Tale workflow trigger to fire a run — and outbound — Tale POSTs to your URL when something it cares about happens. The two halves share the same retry policy (exponential backoff with jitter) but authenticate differently: inbound requests carry their credential as a token in the URL, outbound deliveries are signed with HMAC-SHA256 over the body. Read this when you are wiring an integration that needs to react to events in either direction. Come back when a webhook is firing but the receiver does not see it, or when retries are not behaving the way you expected. ## A worked outbound webhook When an event Tale watches happens — a workflow execution finishes, an agent finishes a reply, a document write completes — Tale POSTs the event to your configured URL: ```http POST https://your-host.example.com/webhooks/tale Content-Type: application/json X-Tale-Event: workflow.execution.completed X-Tale-Signature: sha256= X-Tale-Delivery: X-Tale-Timestamp: 1717000000 { "event": "workflow.execution.completed", "data": { "workflowId": "...", "executionId": "...", "status": "succeeded", ... } } ``` Verify the signature before trusting the body: HMAC-SHA256 over the raw body using the per-endpoint secret, hex-encoded. Compare in constant time. Reject any request older than five minutes by checking `X-Tale-Timestamp` against your clock. ## A worked inbound trigger When your system needs to fire a Tale workflow, POST to the webhook URL Tale mints when you add a webhook trigger to the workflow: ```bash curl -sS https://your-host.example.com/api/workflows/wh/ \ -H "Idempotency-Key: order-12345" \ -H "Content-Type: application/json" \ -d '{ "orderId": "12345", "amount": 199.0 }' ``` The token in the URL path is the credential — no Authorization header is needed, so treat the whole URL as a secret and delete the webhook to revoke it. The body becomes the input of the workflow's first step. A fresh accept returns `{ "status": "accepted", "workflowSlug": "..." }`; a replay with the same `Idempotency-Key` returns the earlier run's `executionId` instead of starting a new one. ## Signing and verifying Outbound: the per-endpoint signing secret is shown once when you add the endpoint under **Settings > Integrations** or in the workflow editor's webhook trigger panel. Tale signs every body with HMAC-SHA256 using that secret; verification is constant-time string compare. Inbound: there is no signing — the token in the URL is the auth. If you cannot keep the URL secret, do not hand it out; delete the webhook to rotate it. ```python import hmac, hashlib def verify(body: bytes, signature: str, secret: str) -> bool: expected = "sha256=" + hmac.new( secret.encode(), body, hashlib.sha256, ).hexdigest() return hmac.compare_digest(expected, signature) ``` ## Idempotency Inbound: pass `Idempotency-Key` on every trigger call. Tale stores the key against the resulting execution for 24 hours; a retry with the same key returns the same execution ID without re-firing the workflow. Outbound: every delivery carries a unique `X-Tale-Delivery` UUID. Use it to de-duplicate on your side — Tale retries on non-2xx responses, and the same delivery UUID will appear on every retry until the receiver acknowledges. ## Retries Outbound retries follow exponential backoff with jitter, capped at 24 hours of attempts. The schedule is: - Immediate retry on a 5xx or a timeout. - 30 s, 1 m, 5 m, 30 m, 2 h, 8 h, 24 h after the first failure. - After 24 h with no 2xx, the delivery is marked failed; the audit log records it. Inbound retries are the caller's responsibility — Tale's response indicates success or failure of the trigger, not of the workflow's steps. If you want to retry, use a stable idempotency key. ## Where this fits Webhooks are the seam between Tale and external systems on both sides. The [API reference](/develop/api-reference) covers the synchronous half — the endpoints you call when you want a value back immediately. The [Triggers reference](/platform/automations/triggers) covers the workflow side of inbound webhooks — the configuration that turns a POST into a workflow run. # Your first day running a workspace Source: https://tale.dev/docs/get-started/admins This journey is for the person accountable for the workspace. In fifteen minutes you create the organization, connect the provider that makes chat answer, bring in your first teammates, and learn where the governance controls live before you need them. You need an account on a running instance ([quickstart](/get-started/quickstart)); on a brand-new instance the first account is automatically the **Owner**, which carries every permission below. If you arrived via the quickstart, your organization already exists — skip to connecting a provider. A fresh sign-in without one lands on the creation wizard: the **Organization name** is the display name your team sees in the corner of every page — pick something that survives a rebrand. The wizard then offers to connect an AI provider and finishes on the dashboard. ![The create-organization wizard on its workspace step, with Northlight Labs typed into the Organization name field and the Next button enabled.](/images/get-started/org-create-wizard.webp) Nothing answers until a provider is connected. If you skipped the wizard's provider step, open **Settings > AI providers** and click **Add provider** — paste an [OpenRouter](https://openrouter.ai) key for the widest model catalog, or any OpenAI-compatible provider. A confirmation on the provider row means the key validates; from that moment every agent in the workspace can answer. ![The AI providers settings page listing one connected provider, OpenRouter, with its base URL and a count of 52 models.](/images/get-started/settings-providers.webp) To add people, open **Settings > Organization**, scroll to the **Members** section, and click **Add member**. Each person lands with a role that bounds what they can do: **Member** reads and chats, **Editor** builds agents and knowledge, **Developer** wires up workflows, automations, and API access, **Admin** runs the workspace. Start people low — raising a role later is one click, and un-leaking access is not. ![The Organization settings page with its Members section listing the workspace owner Alex Rivera and an Add member button.](/images/get-started/settings-organization-members.webp) A teammate who signs in and gets an answer in chat proves the whole chain — account, role, provider — without you standing next to them. You will not need policies on day one, but you should know the door: **Settings > Governance** holds audit logs, usage analytics, content policies, guardrails, and retention. The one habit worth starting today is skimming [audit logs](/platform/admin/governance/audit-logs) after the first week — it shows you what your workspace actually does. ## Where you are now The workspace stands: a provider answers, the team is in with bounded roles, and you know where the controls live. The full permission matrix is [Members and roles](/platform/admin/members-and-roles); [Admin overview](/platform/admin/overview) maps every pane you now own; and when compliance asks, [governance](/platform/admin/governance/audit-logs) is the section you show them. # Your first day integrating with Tale Source: https://tale.dev/docs/get-started/developers This journey is for the person wiring Tale into other systems. In ten minutes you mint an API key, make your first authenticated request, and know which door to knock on for chat, workflows, and documents. You need the **Developer** role or higher (the API settings are hidden below it) on a running instance — [quickstart](/get-started/quickstart) if you have none. Replace `your-host.example.com` below with your instance's host. To get a credential your scripts can hold, open **Settings > API > REST** and click **Create API key**. Name it for the system that will use it — keys are listed by name, and a year from now "zapier-bridge" beats "test". The key value shows once, on creation; store it in your secret manager, not in code. ![The REST API keys settings page listing two keys — Production ingest and CI pipeline — each showing only its key prefix, the date it was added, and a Never used marker, beside a Create API key button.](/images/get-started/settings-api-keys.webp) The shortest useful call lists the agents your key can see. The key rides as a bearer token; the workspace context is inferred from the key itself: ```bash curl -sS https://your-host.example.com/api/v1/agents \ -H "Authorization: Bearer $TALE_API_KEY" ``` A JSON array of agents — including the built-in Assistant — proves the key, the header, and the route. A `401` means the token header is malformed or the key was revoked. ## The rest of the surface Everything else is variations on that request. The OpenAI-compatible endpoints (`/api/v1/chat/completions`, `/api/v1/models`) mean existing SDKs work by swapping the base URL; workflows run by slug over `/api/v1/workflows//run` with the same Bearer key, or fire from outside over webhook URLs of the form `/api/workflows/wh/` — the token in the URL is the credential; documents upload over `/api/v1/documents`. The [API reference](/develop/api-reference) is the complete inventory with auth, shapes, and limits. ## Where you are now You hold a working credential and have seen the request shape every endpoint shares. From here, [call Tale from a script](/tutorials/developer/call-tale-from-a-script) turns the curl into a real integration, [trigger a workflow via webhook](/tutorials/developer/trigger-automation-via-webhook) covers the push direction, and [webhooks](/develop/webhooks) documents the payloads Tale sends you. # Your first day building agents Source: https://tale.dev/docs/get-started/editors This journey is for the person who turns "the team keeps asking the same questions" into an agent that answers them. In fifteen minutes you create an agent, shape how it behaves, and watch it answer in chat — the loop every later agent refines. You need the **Editor** role or higher (the Agents section is hidden from members) on a workspace where chat already answers — that is the [quickstart](/get-started/quickstart). To start an agent teammates can pick in chat, open **Agents** in the sidebar and click **Create agent**. Name it for the job, not the technology — "Support Triage" beats "GPT Helper" — because the name is what teammates pick from the chat composer later. The editor opens on the **General** tab: the display name teammates see, a one-line description, and the agent type. The switch that matters on day one is **Visible in chat** — without it the agent exists but nobody can pick it from the composer. ![The agent editor's General tab for the Assistant agent, showing the agent type options, the Visible in chat toggle, and the display name field.](/images/get-started/agent-editor-general.webp) Open **Instructions & models** — the knob that matters most. Write one paragraph as if briefing a new colleague: the voice to answer in, the domain it owns, and the cases it should refuse. Concrete beats complete — you will refine after seeing real replies. ![The agent editor's Instructions & models tab showing the system prompt field and the ordered model list for the Assistant agent.](/images/platform/agent-editor-instructions.webp) The same tab binds the model: pick one from the workspace's configured providers, or leave routing on automatic so Tale resolves the best available model per request. Click **Save** — an **Agent saved** toast confirms the write. Open **New chat**, pick your agent from the agent picker, and ask something squarely inside the instructions you wrote. Then ask something the instructions say to refuse. ![The chat composer's agent picker open, listing the agents available in the workspace.](/images/platform/chat-agent-picker.webp) An on-voice answer to the first message and a refusal to the second means the instructions bind — the agent is real. ## Where you are now You have shipped the smallest real agent: instructions, a model, a place in the picker. The full model behind what you touched is [Agent concepts](/platform/agents/concepts) — instructions, knowledge, tools, and model as four knobs. The natural next build is [your first agent end to end](/tutorials/editor/first-agent-end-to-end), which adds knowledge bindings and a real domain; after that, [agents with knowledge](/tutorials/editor/agent-with-knowledge) and [delegation between agents](/tutorials/editor/delegate-between-agents) take the same loop further. # Your first day using Tale Source: https://tale.dev/docs/get-started/members This journey is for everyone who uses Tale rather than configures it. In fifteen minutes you chat with an agent, add a document the whole workspace can draw on, and learn where shared work lives — the three moves that cover most days. You need a signed-in account on a workspace where chat already answers — that is the [quickstart](/get-started/quickstart). Chatting and browsing work with the **Member** role; the two write moves below (uploading a document, moving a task) need **Editor** or higher — if a button is missing for you, that is the role boundary, not a broken workspace. You already sent a first message in the quickstart — this time watch what the agent does with it. Click **New chat**, ask something from your actual work, and expand the collapsible tool-call boxes above the reply: they show what the agent read or ran before answering. To attach a file to a single conversation, paste it, drag it into the composer, or use the attach control — the agent reads it for that chat only. [Attachments](/platform/chat/attachments) covers what is accepted. Chat attachments vanish with the conversation; knowledge persists. To make a document available to every agent and teammate, open **Knowledge > Documents** and click **Upload documents**, then **From your device**, pick the file, and click **Upload**. The document appears in the table and is indexed in the background — once indexed, agents cite it in their answers. The upload menu appears for Editors and up; with the Member role you read and search the library, and hand the file to an Editor to add. ![The Knowledge Documents table listing three uploaded text files with their indexing status.](/images/get-started/documents-list.webp) Ask a new chat a question only your document can answer. A reply citing the document proves the index works end to end. Open **Projects** in the sidebar. A project bundles everything about one effort — tasks on a board, shared files, project chats, and its own agents. Open a project and switch between **Board** and **List** on the Tasks tab; with edit access (Editor and up) you drag a task between columns to update its status, and the card staying in its new column after a reload means the change persisted for everyone. ![A project task board titled Website relaunch with seven task cards spread one or two per column across Backlog, To do, In progress, In review, Done, and Cancelled.](/images/platform/projects-task-board.webp) Chats never disappear silently. Click **Show chats** above the composer to open the history sidebar — every chat you can resume in this workspace, newest first. Renaming a chat gives it a title that survives; deleting one moves it to the workspace trash rather than destroying it. ## Where you are now You can chat, feed the workspace knowledge, and navigate shared work — the member's daily loop. The natural next reads are [Chat basics](/platform/chat/basics) for the mental model behind the composer, and [Use projects](/tutorials/member/use-projects) for a deeper project walkthrough. When you are ready to build an agent of your own, switch to the [editor journey](/get-started/editors). # Quickstart Source: https://tale.dev/docs/get-started/quickstart This is the shortest path to a working chat with an agent: get an instance, sign in, send a message, watch the reply stream. It takes about five minutes on a ready instance and fifteen if you stand one up on your own machine, and it ends with the screen below — a real answer from an agent over your workspace. ![A chat thread showing a user question about onboarding feedback and an assistant reply containing a markdown table of three themes.](/images/platform/chat-thread-reply.webp) ## Get an instance The two editions run the same product — pick by who should operate the stack. With [Docker](https://www.docker.com/products/docker-desktop) running, three commands stand up the whole stack on your machine: ```bash curl -fsSL https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.sh | bash tale init my-project && cd my-project tale dev ``` The first run pulls images — expect five to ten minutes. When the browser opens, sign up: the first account claims the **Owner** role and creates your organization. The [self-hosted quickstart](/self-hosted/install/quickstart) covers every step in depth, including Windows and troubleshooting. Cloud instances are set up for you: fill in the [demo request form](https://tale.dev/request-demo) and the Tale team provisions your own instance. Once it is ready, open it and sign up — the form asks for your name, email, and a password; verify the email link when it arrives, name your organization, and you land in the dashboard. The setup wizard offers to connect an AI provider right away — paste an [OpenRouter](https://openrouter.ai) key there and chat works immediately. The [admin journey](/get-started/admins) walks the same wizard with screenshots when you want more than the happy path. ## Send your first message Click **New chat** in the sidebar. The composer at the bottom of the screen is where everything starts: the agent picker on the left, the model picker beside it, and the message field with send on the right. The composer waiting with **Assistant** and **Auto** preselected means you are ready to send. ![The empty chat composer, its placeholder inviting a question about contacts, products, or documents, above a toolbar row carrying the attach and prompt-library controls, the agent and model pickers, and the mute, microphone, and send buttons.](/images/platform/chat-composer.webp) Leave the agent on **Assistant** and the model on **Auto** — Tale resolves the best available model at request time. Type a question and send it. The reply streams in token by token; when the agent reasons before answering, a collapsible thinking line appears above the reply. A streamed reply that answers your question means the whole chain works — provider, model routing, and agent. You have a working workspace. ## Where you are now You have a running instance and an agent that answers. The next fifteen minutes depend on your role: the [member journey](/get-started/members) covers documents and projects, the [editor journey](/get-started/editors) publishes your first specialist agent, the [admin journey](/get-started/admins) sets up the team and providers, and the [developer journey](/get-started/developers) gets you an API key and your first request. # Tale documentation Source: https://tale.dev/docs/ You chat with models over your own documents, build agents that handle a job end to end, run automations in the background, and manage customer conversations from one inbox — with your choice of AI providers and your data pinned to a region you control. Every feature, API, and role is identical across the two editions; the only difference is who runs the stack. Start with the quickstart, then follow the journey that matches your role. From a running instance to a working chat reply, on Cloud or your own machine. ## Pick your journey Four day-one journeys, one per role. Each takes about 15 minutes and ends with something working. Your first chat, your first document, your first project — the member's first day. Publish a minimal agent and watch it answer in chat — the editor's first day. Mint an API key and make your first authenticated request — the developer's first day. Set up the workspace, invite the team, connect a provider — the admin's first day. ## Pick your edition Tale operates the stack — pick this when running infrastructure is not where the team should spend its hours. Install Tale on your own VPC, on-premises hardware, or in an air-gapped environment. ## Go deeper The canonical feature reference, identical for Cloud and self-hosted. Role-indexed walks from "I want to do X" to a working result. REST API, webhooks, integration SDK, contributor workflows. ## Where this fits Once you have walked a get-started journey, the rest of the docs sit one click away: [Platform](/platform) is the canonical reference for every user-visible feature, and [Tutorials](/tutorials/overview) go deeper on complete tasks. Source, issues, and release announcements live at [GitHub](https://github.com/tale-project/tale). # Agents (admin view) Source: https://tale.dev/docs/platform/admin/agents The Admin agents view is the org-wide directory of every agent that exists in Tale, regardless of who built it. Editors and Developers see only the agents they have access to in their own area; Admins and Owners see all of them, plus the per-agent governance levers and the per-agent audit trail. This page covers the Admin surface — what the table shows, what an Admin can change, and what stays under the agent owner's control. This page does not teach you how to build an agent. That is the Editor view under [Agents](/platform/agents/concepts). What follows is the supervisory side: how to find an agent, how to step in when one needs attention, and how the role boundaries hold when you do. ![The agents list with a folder expanded to show agent rows, each naming an agent alongside its primary model and category.](/images/platform/agents-list-expanded.webp) ## What the table shows Open **Settings > Agents** to land on the org-wide list. Each row names an agent and shows its primary model, its category, the team it belongs to (if any), and the date it was last edited. The list is searchable by name and filterable by category, team, and status (active or disabled). The default sort is most-recently-edited first — useful when you want to see what changed since the last time you looked. Clicking a row opens the same agent editor an Editor or Developer would see, but with the Admin lens on: every tab is visible, every binding is editable, and the audit-log tab shows the full edit history with the actor and the diff for each save. ## What an Admin can do that an Editor cannot Admins inherit every permission Editor and Developer carry on the agent surface. Beyond those, the Admin view adds three governance moves: - **Disable an agent.** A disabled agent stops appearing in pickers and stops responding to new requests, but its conversations, executions, and audit trail are preserved. Re-enabling restores the previous behaviour. Reach for disable when an agent is misbehaving and you need to stop it without losing context. - **Reassign ownership.** An agent's owner is the team or member responsible for it. Reassigning transfers the agent to another team or member; the previous owner loses write access unless they share the new team. Reach for reassignment when a team is reorganised or an owner leaves. - **Apply a governance policy.** Admins can attach a governance policy to an agent — required approvals on writes, allowed tool families, allowed integrations. The policy overrides the agent's own configuration if there is a conflict; the agent's owner sees the policy as a read-only badge in the editor. ## What stays with the agent owner Most everyday editing stays with whoever built the agent. Renaming, editing instructions, adjusting the knowledge bindings, toggling tools, switching models, publishing new versions — all of that happens in the agent editor under the owner's permissions. The Admin view is for stepping in, not for taking over. If you find yourself editing other people's agents routinely, the right answer is usually a governance policy that scopes the behaviour, not a manual edit. ## Audit and history Every save on an agent lands in the audit log with the actor, the timestamp, and the field that changed. The Admin view exposes the per-agent slice of that log under the **History** tab in the agent editor. The same data is also reachable from the org-wide audit log under **Settings > Governance**. ## Where this fits The Admin agents view is the supervisory complement to the Editor's build view — same agents, different lens. Most of the time you should reach for it only when something needs attention; the day-to-day work happens on the agent editor under [Agent concepts](/platform/agents/concepts). When the right answer is to scope behaviour for a class of agents rather than one of them, the next read is the governance policy surface — see [Members and roles](/platform/admin/members-and-roles) for how policies attach to roles. # API keys Source: https://tale.dev/docs/platform/admin/api-keys API keys are the org-wide credentials Tale issues so external code can call its REST API without a human in the loop. A key authenticates the caller as the organisation, scoped by the role you pick when you mint it. Admins and Developers manage keys; other roles cannot see the page. This is the reference for what a key is, how to create one, how to scope it, and how to retire it without breaking anything that depends on it. The keys listed here are different from the per-user session tokens Tale issues when someone signs in. Those are short-lived and tied to a person; API keys are long-lived and tied to the organisation. Reach for an API key when you wire a script, a cron job, an internal service, or a third-party integration to Tale; reach for the in-product UI when a person is at the keyboard. ![The REST API keys settings page listing two keys, each showing only its prefix, the date it was added, and a Never used marker, beside a Create API key button.](/images/get-started/settings-api-keys.webp) ## Creating a key Open **Settings > API keys** and click **Create API key**. Give the key a name that says who or what will use it (`Billing sync`, `Slack relay`, `ops-cron`), pick the role it should carry, and pick the expiry. Tale shows the secret exactly once on creation — copy it into your password manager or your deployment system before you close the dialog. After that, only the key's prefix is visible from the table. The role you pick scopes everything the key can do. A key carrying the Developer role can read every resource and write to most; a key carrying the Member role can read the knowledge base and start chats but not configure anything. Pick the smallest role that does the job — keys are exactly as dangerous as the role they carry. ## What the table shows The API keys table lists each key by name, prefix, role, creator, last-used timestamp, and expiry. The prefix is the first eight characters of the secret — enough to identify the key in logs without exposing it. The last-used timestamp updates on every successful request the key makes; a key that has not been used for weeks is usually safe to retire. The filter row lets you narrow by role, by creator, and by expiry window. The default sort is most-recently-created first; the secondary sort is most-recently-used. ## Rotating a key To rotate, create the new key first, deploy it to the system that uses the old one, verify the new key works (the last-used timestamp updates), and only then revoke the old one. Tale does not auto-rotate keys; the discipline of overlap is yours to keep. Rotation is the right move whenever a key is suspected of having leaked, whenever someone with access to the key leaves the organisation, or on whatever cadence your security policy mandates. ## Revoking a key Click the row, then **Revoke**. A revoked key stops authenticating immediately — any in-flight request completes, but the next one fails with `401`. Revoked keys stay in the table for the audit trail; the row badges them as revoked and shows who revoked them and when. There is no undo for revocation; if you revoke the wrong key, mint a new one. ## Scopes and limits Each key carries the permissions of its role at the time of every request, not the time of creation. If you change a role's permissions through a governance policy, every key that carries that role inherits the change on the next request. The org's rate limits apply per key, not per organisation; a noisy key does not throttle a quiet one. A key can be restricted further by IP allowlist on creation. The allowlist takes a comma-separated list of CIDR blocks; requests from outside the list fail with `403`. Reach for the IP allowlist when the calling system has a stable egress and you want defence in depth. ## Where this fits API keys are the bridge between Tale and external code; they sit beside [Integrations](/platform/admin/integrations) (third-party systems Tale calls out to) and [Webhooks](/platform/agents/webhook-triggers) (systems that call into Tale on events). The natural next read is the REST API itself — see the API reference in the Develop tab for the surface a key authenticates against, and see [Members and roles](/platform/admin/members-and-roles) for the role-to-permission map every key inherits. # Branding Source: https://tale.dev/docs/platform/admin/branding Branding is the surface that swaps Tale's default chrome for your organisation's own. The page covers the assets the platform skins — logo, favicon, and the accent colour the palette derives from — and explains where each one shows up so you can preview before you save. The product name itself follows your organisation's name automatically, so there is no separate field to fill. Admins reach for branding when a self-hosted instance ships to an external audience or when an internal rollout needs to feel native to the company. Only Admins and Owners can edit branding. Everyone else sees the result; the form itself is hidden from Editors, Developers, and Members. ![The Branding settings page with logo and favicon uploads, an accent colour field, and a live preview pane on the right.](/images/platform/settings-branding.webp) ## Where branding lives Open **Settings > Branding**. The form has three sections (logo upload, favicon upload, accent colour) and a live preview that mirrors the sidebar with the values you are editing. Save commits the change for every member of _that_ organisation on their next page load — there is no per-user override. Branding is scoped to one organisation. Each organisation keeps its own logo, favicon, and accent colour, so switching organisations swaps the chrome to that organisation's branding rather than carrying the previous one's over. Editing here changes only the organisation you are currently in. ## The product name There is no "app name" or "text logo" field. The wordmark in the sidebar header and the name in the browser tab title are your organisation's own name, which you set on the **Settings > Organization** page. Rename the organisation and the chrome follows on the next page load. Upload a logo image (below) and it takes the wordmark's place; with no logo, the organisation name is rendered as the text wordmark. ## The assets **Logo** is an image — PNG, SVG, or JPG. The platform renders it at sidebar height; aim for a transparent background and a wordmark that reads at roughly 32 pixels tall. The logo is a single upload used on both themes, so pick a mark that reads on light and dark backgrounds. With no logo, the chrome falls back to your organisation's name as a text wordmark. **Favicon** is the tab icon. Upload a light and a dark variant so the icon stays legible whichever theme the operating system has chosen — or leave it blank and Tale derives one from your logo the moment you upload it, so a single upload skins both the sidebar and the browser tab. An explicit favicon always wins over the auto-derived one. **Accent colour** is the single colour the branded palette derives from — buttons, focus rings, selection states, and the sidebar's active row all take their tone from it. It accepts any hex value, picked once for both light and dark mode; Tale derives a legible palette per theme, so a colour that would be hard to read against one theme's background is nudged into contrast for that theme only while the other stays untouched — the same brand reads cleanly on both. The preview reflects the derived palette for the theme you are currently viewing. ## A worked rebrand To rebrand an instance for `Acme Corp`, first set the organisation's name to `Acme Corp` on the **Settings > Organization** page — that name becomes the sidebar wordmark and the browser tab title. Then open **Settings > Branding**, upload the company wordmark as the logo, and paste the brand hex (`#3B82F6` for the example) into the accent colour field. Leave the favicon blank and Tale generates one from the logo. The preview pane on the right updates as you type. Save commits the change; the sidebar, the browser tab, and the favicon reflect the new branding immediately. ## The custom login screen The sign-in, sign-up, and password-reset screens render before you have picked an organisation, so there is no organisation in scope to brand them with. They show the platform's default branding rather than any single organisation's; per-organisation branding takes over the moment you land inside that organisation's workspace. Sign out and reload the login URL to verify which assets the pre-auth screens use. ## Where this fits Branding is the visual layer that sits above every other admin surface; SSO, email, and audit logs all carry the branded chrome to your members. Because the product name is the organisation's own name, keep it sharp on the [organization](/platform/admin/members-and-roles) settings. Pair branding with [providers](/platform/admin/providers) so the model names that show in the chat header match the chrome around them, and with [members and roles](/platform/admin/members-and-roles) so the people who can edit branding are the same people who own the rest of the org's chrome. # Changelog Source: https://tale.dev/docs/platform/admin/changelog The changelog is the in-product viewer that surfaces release notes for the Tale platform itself — not for content your members produce. After a self-hosted upgrade or a managed-cloud rollout, the viewer lists what changed between the previous version and the one running now. Admins read it after an upgrade to brief the team and to flag anything that affects how members work. The viewer reads release notes from the Tale repository on GitHub and caches them inside your instance so the page loads even when GitHub is unreachable. ## Where the changelog lives The changelog has two surfaces. The **What's new** page under **Help** lists every recent release with its full notes. The **upgrade toast** fires once per major-version bump and links straight to the page — the toast shows `Upgraded to v` and stays until dismissed so a member who was away does not miss the heads-up. Open the page from the help menu in the top bar, or from the upgrade toast when it appears. The page caches up to roughly thirty recent releases; older ones link out to the GitHub release history. ## What each entry shows Each release entry carries four fields: the version tag, the publish date, the release name (often a short headline), and the release body in Markdown. Tale renders the body the way GitHub does — headings, lists, links, and code fences all survive. Releases that GitHub has not yet published surface a short explainer card with a link to the public release history. ## Scope The changelog is the platform's changelog — what changed in Tale itself. It does not show changes to your agents, your workflows, or your knowledge base; those have their own per-resource history. If you are looking for the version history of an agent or a workflow, open the resource and switch to the **History** tab. The viewer is read-only and visible to every signed-in member. There is no Admin-only flag — anyone with an account can open the page. The data the viewer fetches is public release information from the Tale GitHub repository, so there is nothing org-scoped to hide. ## A worked upgrade After a self-hosted upgrade from `v0.42` to `v0.45`, sign in and look for the upgrade toast in the top right. Click **View** to open the changelog page. The page shows three release entries (`v0.43`, `v0.44`, `v0.45`) newest first, each with the engineer-written notes from the GitHub release. Skim the highlights, share the link with the team if anything needs a wider audience, and the toast clears the next time you reload. When the upgrade spans more than the cached window, the page shows the most recent entries with a banner that links to GitHub for the earlier notes. The cache stays warm for the next reader on your instance. ## Where this fits The changelog is the operator's read-out of what Tale itself just did; it sits next to the audit log (which records what your members did) and the providers page (which tracks which model versions are wired). Pair it with [self-hosted upgrade](/self-hosted/operate/upgrades) when you operate the instance — the upgrade guide walks the version bump, and the changelog reads out the result on the other side. # Enterprise SSO and provisioning Source: https://tale.dev/docs/platform/admin/enterprise-sso Enterprise SSO lets your members sign in with your identity provider (IdP) instead of a Tale password, and SCIM lets the IdP provision, update, and deactivate members and groups automatically — no manual invites. One connection per organisation carries the sign-in protocol, the provisioning policy, and the SCIM token together. Everything lives on one page: **Settings > Enterprise SSO** (admins only). Tale speaks four protocols: **OIDC**, plain **OAuth2**, **SAML 2.0** for sign-in, and **SCIM 2.0** for provisioning. You can enable sign-in, provisioning, or both. ![The Enterprise SSO settings page with the Protocol dropdown set to Microsoft Entra ID and a matching display name, and a sign-in section carrying the redirect URL to register, an issuer URL and client ID filled in from the app registration, an empty client secret, and the requested scopes.](/images/platform/settings-enterprise-sso.webp) ## Choosing a protocol Open **Settings > Enterprise SSO**, pick a **Protocol**, and fill in only that protocol's fields — the rest stay hidden. A **Setup guide** on the same page lists the exact steps and shows the URLs you paste into your IdP. Use **Test connection** before saving to validate the configuration, and **Save** to enable sign-in. - **Microsoft Entra ID** — Microsoft's OIDC, with group-to-team sync over Microsoft Graph. - **Generic OIDC** — any OpenID Connect provider (Google, Okta, Auth0, Keycloak, …). Endpoints are discovered from the issuer. - **OAuth2** — providers without OIDC discovery; you configure the authorization, token, and userinfo endpoints by hand. - **SAML 2.0** — XML-based SSO; you exchange metadata with the IdP. ## Microsoft Entra ID 1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as at least an Application Developer. 2. Go to **Entra ID > App registrations > New registration**, name it, and choose **Single tenant**. 3. Under **Redirect URI**, select the **Web** platform and paste the **Redirect URL** shown on the Tale settings page, then **Register**. 4. On the app's **Overview**, copy the **Application (client) ID** and **Directory (tenant) ID**. Your issuer URL is `https://login.microsoftonline.com/{tenant-id}/v2.0`. 5. Open **Certificates & secrets > New client secret** and copy the secret **Value** (not the Secret ID). 6. In Tale, choose **Microsoft Entra ID**, and enter the client ID, client secret, and issuer URL. 7. For group-to-team sync, add the Microsoft Graph **GroupMember.Read.All** permission under **API permissions** and grant admin consent. 8. For OneDrive and SharePoint document sync, add the Microsoft Graph **Files.Read** and **Sites.Read.All** permissions under **API permissions** and grant admin consent. A new connection requests both by default — the SSO token doubles as the Graph token, so members can import files right after signing in. If the organisation should only sign in, remove the two scopes from the **Scopes** field; the Microsoft 365 entry then stays hidden on the documents page. ## Google Google is configured as a generic OIDC provider. 1. In the [Google Cloud Console](https://console.cloud.google.com), open **APIs & Services > Credentials > Create credentials > OAuth client ID**. 2. Choose the application type **Web application**. 3. Under **Authorized redirect URIs**, add the **Redirect URL** shown on the Tale settings page, and save. 4. Copy the **Client ID** and **Client secret** from the top of the client page. 5. In Tale, choose **Generic OIDC**, enter the client ID and secret, and set the issuer URL to `https://accounts.google.com`. Endpoints are discovered automatically. Google's standard OIDC does **not** return group memberships, so group-to-team sync is unavailable with Google alone — it needs the Admin SDK / Cloud Identity API with a Workspace admin. Sign-in and role-by-claim mapping work normally. ## Generic OIDC and OAuth2 For any other OIDC provider (Okta, Auth0, Keycloak), choose **Generic OIDC**, paste the **issuer URL** and the client ID/secret — Tale reads the authorization, token, and userinfo endpoints from the issuer's `.well-known/openid-configuration`. If a provider exposes OAuth2 but no discovery document, choose **OAuth2** and enter the **authorization**, **token**, and **userinfo** endpoint URLs by hand. When the provider uses non-standard claim names, map **email**, **name**, and **groups** under the connection's advanced fields (dot-paths are supported, e.g. `realm_access.roles`). ## SAML 2.0 1. In Tale, choose **SAML 2.0**. The page shows your **SP metadata URL** and **ACS (reply) URL** — copy them. 2. In your IdP, create a new SAML 2.0 application. Set its **ACS URL** and **Entity ID / Audience** to the SP values shown (or upload the SP metadata URL), and set the **Name ID** format to email address. 3. Under **Import IdP metadata**, paste the IdP's federation-metadata URL and click **Import** — or click **Upload XML** if your IdP only offers a downloadable file. Tale parses the metadata and fills the entity ID, sign-on URL, and signing certificate fields below, so there's nothing to retype by hand. All three stay editable, so review the imported values (or fill them in yourself, if your IdP publishes no metadata document) before saving. 4. Map the **email**, **name**, and **group** attributes in your IdP; if their names differ from the defaults, set the matching attribute names in Tale's advanced fields. Tale supports both IdP-initiated SAML (the IdP posts an assertion to the ACS URL) and SP-initiated SAML (a member clicks **Sign in with SSO** and Tale redirects to the IdP). Signed assertions are required; encrypted assertions are supported when you supply an SP keypair. ## Several organizations on one deployment A deployment can host more than one organization, each with its own connection. Click **Continue with SSO** on the login page, then pick your organization from the list — each entry shows the connection's **Display name**. That name is visible to anyone on the login page, so set a clear display name per connection in **Settings > Enterprise SSO**. ## Provisioning: roles and teams Every protocol shares one provisioning policy: - **Default role** — the role a newly provisioned member receives (Member by default). - **Auto-assign roles** — when on, role-mapping rules map a job title, app role, group, or claim to a platform role; the default role applies when nothing matches. - **Sync groups to teams** — when on, each of the user's IdP groups becomes (or joins) a team of the same name on sign-in; **Exclude groups** skips noisy groups (comma-separated). ## SCIM provisioning (users and groups) SCIM lets your IdP push changes without anyone signing in. In the **SCIM provisioning** section, click **Generate token** — copy it once (it is never shown again) — and paste it, along with the **SCIM base URL** shown, into your IdP's provisioning settings. The IdP authenticates with the token as a bearer credential; Tale resolves the organisation from the token, so it is the tenant boundary. Tale implements SCIM 2.0 **Users** and **Groups**: create, read, list (with `userName`/`displayName` filters), replace, patch, and delete. Provisioned users map to organisation members; groups map to teams. **Deactivation is soft** — when the IdP sets a user inactive (`active: false`), the member's role is set to `disabled` (which removes their access), and re-activation restores their prior role. A SCIM **delete** removes the membership from the organisation; the user account itself is kept, and re-provisioning attaches it again at the connection's default role. The organisation owner can never be de-provisioned via SCIM. ## Verifying Use **Test connection** for OIDC/OAuth2 to confirm discovery and credentials before saving. For SAML, download the SP metadata into your IdP and run a test login. For SCIM, most IdPs offer a "test" or "provision now" action that creates a sample user — confirm it appears under **Settings > Members**. End-to-end SSO sign-in is best verified against your real IdP in a staging organisation. # Audit logs Source: https://tale.dev/docs/platform/admin/governance/audit-logs The audit log is the immutable record of every consequential action inside your organisation. Every sign-in, role change, provider edit, agent save, workflow run, and sandbox invocation lands here with the actor, the resource, the before/after state, and the timestamp. Admins and Owners read this when an audit asks who touched a resource and when, when a compliance officer needs an export, or when something goes sideways and the question is _who changed what at 03:14_. This page is the reference for the columns, the filters, the categories, and the export formats. The retention window for audit rows is set on the same Governance area under retention policy — keep it long enough to satisfy your compliance requirements before rows roll off. ## A worked filter To find the moment a member's role was changed, open **Settings > Governance > Logs**, set the **Category** filter to **Member**, and search for the actor or the target by name. Each row expands to the full payload — previous state, new state, the IP if the request was over the wire, the actor type (user, system, API, workflow). Export the filtered set as CSV or JSON from the toolbar above the table. ## The columns | Name | Type | Required | Description | | -------------- | -------- | -------- | ----------------------------------------------------------------------------------------- | | Timestamp | ISO 8601 | yes | Server time the action committed. | | Action | string | yes | The semantic action — `update_member_role`, `provider_created`, `agent_saved`. | | User | string | yes | Display name of the actor; `System`, `API`, or `Workflow` when the actor is not a person. | | Resource | string | yes | The resource the action touched — `agent`, `provider`, `member`, `workflow`. | | Category | enum | yes | Auth, Member, Data, Integration, Workflow, Security, Admin, AI, Skill, Agent. | | Status | enum | yes | Success, Failure, Denied. | | Changed fields | JSON | no | The diff between previous and new state for update actions. | ## Filters Filter by date range, category, status, actor, resource, or free-text search across action names. Combine filters — a date range plus the **Security** category plus **Denied** status surfaces the failed sign-in attempts in a window. Filter state is reflected in the URL, so a saved link reopens the same view. ## Exporting Two export formats ship: CSV for spreadsheets and JSON for downstream systems. Both honour the active filters — what you export is what you see. Set the filters you want (the worked filter above is the pattern), then choose CSV or JSON from the toolbar above the table. Large exports stream as a download; the toolbar reports progress and completes with the file size and row count. The CSV arrives as `audit-logs-.csv`, one row per action, with a flat column per field; timestamps are ISO 8601 in UTC and any value containing a comma is quoted: ```csv timestamp,action,category,actorEmail,actorId,actorType,actorRole,resourceType,resourceId,resourceName,status,errorMessage 2026-01-14T03:14:07.000Z,member.role_changed,Member,admin@acme.example,usr_8f3a,user,owner,member,usr_2b91,jordan@acme.example,success, 2026-01-14T03:15:22.000Z,provider.updated,Provider,admin@acme.example,usr_8f3a,user,owner,provider,prov_openai,OpenAI,success, ``` The JSON export (`audit-logs-.json`) carries the same rows as full objects plus the fields CSV flattens away — the `previousState`/`newState` diff and the per-row `integrityHash`. Reach for JSON when a downstream system needs the before/after payload or has to re-verify each row against the SHA-256 chain (see [Retention and integrity](#retention-and-integrity)); reach for CSV when a person opens it in a spreadsheet. ## Retention and integrity Audit rows are immutable: edits and deletes are themselves audited, and the row schema carries an integrity hash you can verify against the export. A scheduled daily check re-verifies the hash chain server-side and records a `security` audit entry if verification fails, so tampering or an out-of-band deletion surfaces even when no admin runs the manual check. A failed check also raises a critical in-app notification to the organisation's admins and fans out to Slack when a Slack notification channel is configured. Admins can verify the chain on demand from the **Chain integrity** panel at the top of this page — it shows the current status, the last automated check time, and a **Verify now** button — and a failed check's notification deep-links to the flagged row so an admin lands on the break instead of the top of the log. Retention defaults to 90 days and is configurable on the retention policy page (30 to 365 days). Rows that age out are removed by the next cleanup pass — there is no soft-delete window for audit data. ## Where this fits The audit log is the read side of every other governance feature: legal hold names the holds it placed, data subject requests log every cascade step, the run-code policy logs the URLs each sandbox tried to reach. When a question starts with _who, when, what_, the audit log is the answer. The companion page is the [retention policy](/platform/admin/governance/policies-and-limits) — it controls how long these rows stay before cleanup removes them. # Content and models Source: https://tale.dev/docs/platform/admin/governance/content-models Content and models is the surface where you decide which LLMs the people in your organisation can reach and which one each group lands on by default. It pairs an allowlist or blocklist per scope (org, team, role, user) with a default-model rule the resolver applies when no agent or conversation has overridden the choice. Admins and Owners read this page when a compliance rule pins a workload to an approved model, when a team should default to a cheaper model than the rest of the org, or when a new model from an existing provider needs to be made reachable. ![The Content and Models governance page showing the mandatory system-prompt prefix and suffix fields filled with the org's house rules, above a default-models table carrying three rules: a default for all users, and role rules for Developer and Member, each pinned to an OpenRouter model.](/images/platform/governance-content-models.webp) ## A worked default To set the default model for the Editor role, open **Settings > Governance > Default Models** and click **Add rule**. Pick **Role** as the scope, **Editor** as the target, then pick the provider and model. Save and the next request from any Editor without an explicit per-agent or per-conversation model lands on the rule's model. More specific scopes win — a user rule beats a team rule beats a role rule beats the org default. ## The two layers **Model access** is the allowlist or blocklist that gates which models a scope can use at all. A model not on the allowlist is invisible to that scope — the picker hides it and the resolver refuses to bind to it, even if an agent has it pinned. Reach for the allowlist when a regulator names the approved models; reach for the blocklist when a single model should be off-limits everywhere else. **Default models** is the resolver rule that picks the model when nothing else has — no per-agent override, no per-conversation override. The default applies the moment the user starts a fresh chat and applies as the fallback when an agent's pinned model is unreachable. ## Scopes and precedence Both layers carry a scope: org, team, role, or user. The resolver evaluates from narrowest to widest — user wins over team wins over role wins over org default. The model access layer composes with the default-model layer; the default the resolver picks must also pass the access check for the same scope, otherwise the resolver falls back to the nearest permitted model. ## Allowlist and blocklist warnings The default-models editor surfaces a warning when a rule names a model the allowlist for the same scope does not permit, or when the blocklist for the same scope blocks it. The warning does not block saving — the resolver will fall back at request time — but it flags the mismatch so you can fix one or the other. ## Where this fits Content and models is the gate every chat and every agent passes through at request time. Pairing model access with default models lets you ship a tight compliance posture without forcing every agent author to remember which model is approved this quarter. The companion is the [policies and limits](/platform/admin/governance/policies-and-limits) page — it covers the cost and request caps that apply on top of the model choices made here. # Data subject requests Source: https://tale.dev/docs/platform/admin/governance/data-subject-requests Data subject requests is the workflow Tale ships for honouring GDPR Article 17 (right to erasure) and the equivalent CCPA right under California law. Each request becomes a receipt: it names the subject, the reason code, the SLA deadline, and the cascade of rows the system erased across threads, documents, workflow executions, and personal prompt templates. Admins and Owners read this page when a subject files a request, when a deadline is closing in, or when an audit asks for the receipt of a past erasure. ![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.](/images/platform/governance-data-subject-requests.webp) ## A worked filing To file a request, open **Settings > Governance > Data subject requests** and click **File request**. Pick the subject, choose a reason code (consent withdrawn, no longer necessary, unlawful processing, legal obligation, objection, child subject, or contract termination), and add a free-text narrative. The request enters a cooling-off window before the cascade runs — any Admin can cancel during the window. After the window elapses, the cascade erases the subject's threads, documents, workflow executions, RAG embeddings, and personal prompts, and the receipt records counts for each category. ## Status lifecycle | Name | Default | Description | | ----------------- | ------------- | ----------------------------------------------------------------------------------------- | | Pending | initial state | The request is filed and waiting for the cooling-off window or the second admin approval. | | Awaiting approval | dual-control | A second Admin must approve before the cascade runs. | | Running | mid-cascade | The cascade is in flight; partial counters update as each category completes. | | Completed | terminal | Every category erased without error. | | Partial | terminal | Some rows were skipped — usually a legal hold blocked them. | | Failed | terminal | The cascade hit an error; the receipt names the failed category. | | Blocked | terminal | An active legal hold blocks every cascade step. | | Cancelled | terminal | An Admin cancelled before the cooling-off window elapsed. | ## SLA tracking Every request carries a service-level deadline — by default, 30 days from filing. The Requests list shows days-left or an overdue badge per row. Article 12(3) of GDPR permits a single extension for complex cases; the **Extend deadline** action records the extension on the receipt with the requesting admin's name and a narrative. ## Legal hold interaction A subject's data is _not_ erased while it is on legal hold. Rows under hold show as **Skipped by hold** in the receipt's per-category counters; releasing the hold and retrying the request finishes the erasure. The Blocked status fires when a hold covers every category from the start — the cascade does not run, and the receipt reflects the block. ## The cascade categories The receipt breaks the erased rows down by category — threads, documents, workflow executions, prompt templates, RAG documents removed from the vector store. Read the drawer to see counts and the audit timeline; the audit log on the same Governance area carries the full event chain (`gdpr_erasure_requested`, `gdpr_erasure_executed`, `gdpr_erasure_extended`, `gdpr_erasure_cancelled`). ## Where this fits Data subject requests is the compliance face of retention — the audited, dual-controlled path that erases a specific subject on demand instead of the timed sweep retention runs across everyone. The companion page is [legal hold](/platform/admin/governance/legal-hold) — it covers how to pause retention and DSAR cascades for litigation before they run. # Feedback analytics Source: https://tale.dev/docs/platform/admin/governance/feedback-analytics Feedback analytics is the dashboard that turns the per-message thumbs and the per-chat ratings into trend lines. Members leave the feedback inline in chat; this page aggregates it by agent, by model, and over time so the regression in last week's voice change is visible as a number, not a hunch. Admins and Owners read this page when a model swap looks like a downgrade, when one agent is underperforming the others, or when leadership wants the rough quality posture of every agent in the org. ## A worked drill-down Open **Settings > Governance > Feedback** and the default view is the org-wide ratio across the last 30 days. Switch the breakdown to **By agent** to see the ratio per agent — sort by feedback volume to find the agents members are actually using, then click into one to see its model history alongside the same ratio over time. The split-by-model view is the same data sliced on the model that produced each rated reply. ## The two signals **Thumbs feedback** is the per-message signal — a thumb up or thumb down on any agent reply. The thumb carries an optional free-text comment; the comment is per row and never aggregated into the ratio. Members can leave both, edit either, or withdraw entirely; the timeline reflects the latest state. **Chat ratings** is the per-conversation signal — the one-to-five star rating that surfaces at the end of a conversation. Ratings carry an optional comment too. Chat ratings are coarser than thumbs and useful for tracking the agent-level vibe over many turns where individual thumbs would be noisy. ## Breakdowns The dashboard slices by three dimensions: - **Agent** — every agent in the org gets its own row with ratio, volume, and trend. - **Model** — every model that produced a rated reply contributes; useful when you compare a primary against its fallback. - **Time** — the trend is daily for the last 30 days and weekly for longer windows. ## Free-text comments Comments are surfaced under the aggregated numbers as a list. Sort by recency or by sentiment; click through to the conversation in context to see what the rated reply was responding to. Comments are subject to the same retention policy as the conversations they belong to; if a thread is purged or trashed, its comments go with it. ## Where this fits Feedback analytics is the pulse on every agent in the org — the place a regression in voice or model behaviour shows up before someone reports it. The companion is [usage analytics](/platform/admin/governance/usage-analytics) — the same agents and models, sliced by spend and token volume instead of quality. # Guardrails Source: https://tale.dev/docs/platform/admin/governance/guardrails Guardrails is the surface where you configure the three filter layers Tale runs on every chat message in your organisation. Each message passes through content safety (word lists and admin regex), then PII detection (built-in patterns plus custom), then an optional external moderation provider — in that fixed order, on the way in and on the way out. Admins and Owners read this page when a regulator names a content rule, when a leak warrants a tighter policy, or when an agent's replies need to be sanitised before they leave the model. ![The Guardrails governance page showing three status cards — content safety applied to input and output across two categories, PII detection running in mask mode over four built-in patterns, and a moderation provider marked Disabled with no external API configured — above a recent-events feed reporting no events yet.](/images/platform/governance-guardrails.webp) ## A worked layering To configure the layers, open **Settings > Governance > Guardrails**. The overview shows three status cards, one per layer — content safety, PII detection, moderation. Each card links to its own configuration page where you pick whether the layer runs on input, on output, or both, and what it does on a match (block the message, mask the match, or flag and pass). The recent-events table at the bottom of the overview shows the last 50 detections, blocks, and provider errors with their layer, direction, and match category. ## Content safety Content safety is the layer you own. Define one or more categories — hate speech, profanity, a custom regex for an internal codename — and pick a mode per category: **block** refuses the message, **mask** replaces matches with a placeholder, **flag** records the detection without changing the message. Block wins over mask wins over flag when more than one category matches. The layer's word lists and patterns never leave the deployment. Matched text is not stored — only the category, the direction (input or output), and the count of matches end up in the audit event. ## PII detection PII detection ships with patterns for emails, phones, government IDs, payment numbers, and a long tail of regional formats. Add custom patterns if your regulator names a format the built-ins miss. Pick a mode — block, mask with a placeholder, or flag — and an apply direction. Mask is the typical choice for output filtering when the model has been given access to records that include PII it should not echo back. ## Moderation provider The moderation layer is an external classifier — OpenAI Moderation, Azure Content Safety, Perspective API, or a custom HTTP endpoint. Configure the provider's endpoint, an API key, and the category-to-action mapping (each provider returns its own taxonomy; the mapping decides which categories block, mask, or flag). The layer is optional — leave it disabled and only the first two layers run. The provider sits on the network egress path. Failures are configurable per direction: fail-open lets the message through, fail-closed refuses it. The recent-events view shows provider errors, HTTP statuses, and circuit-open events when the layer is rate-limited. ## Recent events Every detection, block, and provider error lands in the recent-events table for 30 days. Filter by layer or by kind; click a row to see the matched categories, the actor, the message id, and the timestamp. Raw matched text is never stored — the events are a tuning surface, not a content archive. ## Where this fits Guardrails is the runtime filter between the user and the model in both directions. Pair it with [content and models](/platform/admin/governance/content-models) so an approved model is also subject to the approved content rules. The companion is the [audit log](/platform/admin/governance/audit-logs) — every block and every mask the guardrail layers apply lands there as a permanent record. # Legal hold Source: https://tale.dev/docs/platform/admin/governance/legal-hold Legal hold is the mechanism Tale ships for preserving evidence under litigation hold. A hold pins a target — a user, a document, a thread, a workflow execution, or the whole organisation — out of reach of the retention sweep and the data-subject erasure cascade. Admins and Owners read this page when counsel asks them to preserve a custodian's data, when a release request needs the dual-control sign-off, or when an audit reconciles which holds were in force on a given date. ![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.](/images/platform/governance-legal-hold.webp) ## A worked placement To place a hold on a user, open **Settings > Governance > Legal hold** and click **Place legal hold**. Pick the target type — user, thread, document, execution, or organisation — pick the specific target, add a reason, and link the hold to a matter if one is open. The hold takes effect immediately; retention sweeps skip the target's rows, the erasure cascade reports them as **Skipped by hold**, and the target row carries the **On legal hold** badge in every list where it appears. ## The four sections **Active holds** is the working list of every hold currently in force. Each row carries the type, the target, the reason, the matter, who placed it, and when. Filter by type or by matter to scope the view. **Release requests** is the dual-control queue. Releasing a hold requires a different Admin to approve the request; approved requests still wait out a cooldown before they take effect. The section splits into _pending approval_ and _approved, awaiting cooldown_ so the queue and the timer are both visible. **Matters** groups holds by case. Each matter carries a name, a case number, and the list of linked holds. Closing a matter files release requests for every linked hold — still subject to the dual-control approval per request. **Release history** is the read-only audit of effected and rejected releases. Use it to reconcile against an opposing counsel's preservation letter or to feed an audit report. ## Hold-and-cascade interaction A hold blocks every retention pass and every erasure step for the target. The trash page shows the **Delete is blocked by an active legal hold** banner when an Admin tries to purge a row under hold. A data subject request whose subject is covered by a hold lands in the **Blocked** status until the hold is released; partial coverage (some threads under hold, some not) lands in **Partial** with per-category counters in the receipt. ## Dual-control Place and release are not symmetric. Place is a single-Admin action — the speed matters when litigation arrives. Release is dual-control: the requesting Admin files, a different Admin approves, and a cooldown window applies between approval and effect so a hasty release can still be cancelled. Both halves of the workflow are audited end to end. ## Where this fits Legal hold is the freeze button on retention. It is the only mechanism that beats the timed retention sweep and the data-subject erasure cascade — both of which respect holds by design. The companion pages are [data subject requests](/platform/admin/governance/data-subject-requests) for the cascade side and [policies and limits](/platform/admin/governance/policies-and-limits) for the retention windows the hold overrides. # Policies and limits Source: https://tale.dev/docs/platform/admin/governance/policies-and-limits Policies and limits is the surface where you cap what your members and agents can consume. Budgets cap tokens, cost, and requests per billing period; feature controls toggle web search, code execution, and file upload by scope; upload policy gates the file types and sizes a member can attach; retention policy decides how long each data type lives before cleanup. Admins and Owners read this page when a workload is over budget, when a feature should be off for a subset of users, or when a regulator names a retention window that differs from the default. ![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.](/images/platform/governance-policies-limits.webp) ## A worked budget To cap an Editor's monthly spend, open **Settings > Governance > Budgets** and click **Add rule**. Pick **Role** as the scope, **Editor** as the target, set the period to **Monthly**, and fill in a max-cost in USD. Save and the next month-period request that would push an Editor over the cap is refused with a budget-exceeded error. A warning threshold below the cap fires an alert before the cap hits. Narrower scopes override broader ones — a user rule beats a team rule beats a role rule — and org-wide limits always apply on top as an additional cap. ## The four policy layers **Budgets** are token, cost, and request caps per scope and period. Scopes are org, role, team, user, or API key. Each rule carries a token cap, a cost cap in USD, an optional request cap, and a warning threshold expressed as a percentage of the cap. An API-key rule targets one issued key (pick **API key** as the scope, then the key from **Settings > API**) and caps only the traffic authenticated with that key — the REST and OpenAI-compatible API — so you can meter a single integration without touching in-app usage. Image generation is metered by cost and request count, not tokens — an image request reports no tokens, so cap image spend with the cost or request limit, not the token limit. **Feature controls** toggle web search, code execution, and file upload per scope, and cap the max context tokens for AI replies. A feature off for a scope hides the toggle in chat and refuses the request server-side. **Upload policy** gates the file extensions, MIME types, and sizes a member can attach. It also caps the total volume per user — useful when storage is metered. Toggle the policy off for a permissive default; toggle it on to enforce the lists. **Retention policy** decides how long each data type (chat history, documents, prompts, audit logs, usage ledger, workflow runs, and more) stays before the cleanup pass removes it. The page shows the operator-imposed bounds, the per-org override within those bounds, and a grace window before hard delete. ## Precedence All four layers share the same scope ladder: user > team > role > org > default. The narrowest rule wins. Where a layer carries an org-wide cap (budgets), the cap applies as an additional ceiling on top of any narrower rule. An API-key budget sits outside the ladder as its own independent bucket: it binds the key's own requests regardless of the owner's user, team, or org caps, so a single credential can be held to a tighter allotment than the person who issued it. ## Retention bounds and approvals Retention policy sits inside operator-imposed bounds — the self-hosted operator sets a floor and a ceiling per category, and the org's value clamps to that range. When the operator proposes a tighter floor or a lower ceiling, the change surfaces as a proposal Admins can apply or reject. Reductions to the policy land with a pending-change banner and a grace window before they take effect — the same grace gives Admins a chance to cancel. ## Session idle timeout Session idle timeout signs members out after a period of inactivity — the session-bound control compliance frameworks ask for (SOC 2 CC6.1). Open **Settings > Governance > Security & Monitoring**, switch on **Enable session idle timeout**, and set **Idle timeout (minutes)** (1–1440, default 30). Members see a warning shortly before the cut-off; after it, the active tab signs out and the login page explains the sign-out instead of presenting a bare form. The window can only tighten the deployment-wide limit, never loosen it. Self-hosted operators set that hard cap with an environment variable (see the [environment reference](/self-hosted/configuration/environment-reference)); the org policy applies on top, and the stricter of the two windows wins. A member of several organisations gets the strictest window across all of them. Enforcement has two halves. The watchdog in the browser ends open, visible sessions on the minute. Closed tabs and abandoned devices are caught server-side by a revocation sweep that runs about every five minutes — a session can therefore outlive the window by a few minutes; when you state the control to an auditor, count the window plus roughly half an hour in the worst case. Every server-side revocation lands in the [audit log](/platform/admin/governance/audit-logs) as `session.idle_revoked`. One caveat for trusted-headers deployments: the reverse proxy owns authentication there, so a revoked session is re-established as soon as the member confirms the sign-in notice — pair the policy with an idle timeout on the proxy or IdP side for a real lockout. ## Where this fits Policies and limits is the budget and gate layer that protects the org from runaway spend and unintended access. Pair it with [content and models](/platform/admin/governance/content-models) so the model the budget caps is also the one the access list permits, and with [retention policy on the same page](#retention-bounds-and-approvals) so the data the org keeps is bounded too. The companion is [audit logs](/platform/admin/governance/audit-logs) — every policy change here lands there as a permanent record. # Run-code policy Source: https://tale.dev/docs/platform/admin/governance/run-code-policy Run-code policy is the surface where you decide which Python and Node packages the sandbox can install at execution time. Skills with scripts and the Run code tool both run in the same sandbox; this policy is the single seam where you tighten or loosen what they can install. Admins and Owners read this page when an agent needs a new library, or when an audit asks why a package was blocked at a given time. ![The Run-code policy governance page with Allowlist picked in the default-mode radiogroup, above a Python allow list holding pandas, numpy, scipy, and scikit-learn, a Python deny list holding paramiko, fabric, pexpect, and scapy, and a Node allow list holding axios, date-fns, dayjs, and lodash.](/images/platform/governance-run-code-policy.webp) ## A worked switch The default mode is **Denylist** with an empty list, which means every package is installable. To switch to a curated set, open **Settings > Governance > Run-code packages**, change the mode to **Allowlist**, and enumerate the packages you trust under **Python allow list** and **Node allow list**. Save and the next sandbox run that requests a package outside the list fails with the **not on the allow list** reason in the audit event. ## The two modes | Name | Default | Description | | --------- | ------- | ----------------------------------------------------------------------------------------------------------------- | | Allowlist | off | Only the listed packages install; everything else is rejected. Use when a regulator names the approved libraries. | | Denylist | on | Every package installs except the listed ones. Use when a small set is known-bad and the rest is trusted. | ## The four lists Each mode reads from two lists — Python and Node. One package per line, or comma-separated. Version constraints are stripped automatically (`pandas==2.1` matches `pandas`), so the policy is name-based and survives library upgrades. Scoped Node packages (`@scope/pkg`) are supported. The lists are independent per language: a Python allowlist plus a Node denylist is a valid combination, and means Python is strict and Node is permissive on the same sandbox. ## The tester The Test panel on the same page lets you paste pip or npm specs and see whether each one would pass under the current draft. It uses your unsaved edits, so you can iterate before clicking Save. Each spec is parsed, stripped of its version constraint, and matched against the lists; the panel reports **Allowed** or **Denied** with the reason — matches-the-allow-list, not-on-the-allow-list, matches-the-deny-list, not-on-the-deny-list. ## Network egress and skills The package policy gates _what_ runs in the sandbox. The same sandbox runs skill scripts — see the [Skills concept](/platform/agents/skills) page. Outbound network from sandbox code is open by default, with cloud-metadata and private-range targets always blocked; on self-hosted deployments the operator can restrict it to a hostname allowlist at the deployment level — the walk lives in [Hardening](/self-hosted/operate/security/hardening). Treat publishing a skill with a script as widening the trust surface for every agent that picks it up; the package policy and the deployment's egress policy together decide what the script can do. ## Where this fits Run-code policy is the gate on the sandbox that backs both the Run code tool and skill scripts. The companion concept is [Agent skills](/platform/agents/skills) — it covers when to publish a script as a skill, and why the package policy is the load-bearing gate. The companion governance page is [audit logs](/platform/admin/governance/audit-logs) — every denied package install lands there with the spec and the reason. # Trash Source: https://tale.dev/docs/platform/admin/governance/trash Trash is the recovery surface for the rows retention has soft-deleted but not yet hard-deleted. When a chat thread, a document, a prompt template, or a workflow run exceeds its retention window, it moves here for the configured grace window before the next cleanup pass removes it for good. Admins and Owners read this page when a member asks for a deleted artefact back, when a workflow deleted the wrong thing, or when an audit needs to know whether a row is still recoverable. ## A worked restore To restore a chat history thread, open **Settings > Governance > Trash** and switch the **Category** filter to **Chat history**. Each row carries the type, the name, the owner, the status, and when it was trashed. Click **Restore** on the row, confirm in the dialog, and the row returns to its source list — chat threads reappear in the conversation inbox, documents in the knowledge base, prompts in the prompt library. Restoring a retention-expired row requires typing `restore` to confirm and is audited as an override of the retention policy. ## The two statuses **Trashed** is the normal soft-delete state. The row's retention window elapsed, it moved to trash, and the grace window is still ticking. Restore returns the row to its source list with no policy override. **Expired** is the second state — the grace window ran out and the row is queued for permanent deletion at the next cleanup. Restore is still possible but is an override: the dialog asks you to type `restore` and the audit log records the override with your name. ## The categories Trash holds rows from many categories. The category filter switches the view per tab: - Chat history (threads) - Documents - Temporary files - Prompt templates - Message feedback - Customers - Vendors - External conversations - Message metadata - Workflow runs - Workflow trigger logs - Usage ledger - Audit logs - Chat filter events - Memory audit Each category honours its own retention window and its own grace window — set on the retention policy in [policies and limits](/platform/admin/governance/policies-and-limits). ## Legal hold interaction Rows under legal hold do not appear in trash — the hold pins them out of reach of every retention step. When you try to delete a held row from its source list, Tale refuses with the **Delete is blocked by an active legal hold** message. Release the hold to let retention sweep the row through the trash window the way other categories flow. ## The grace window The grace window is configurable per category on the retention policy. A grace of zero skips trash entirely — the cleanup pass hard-deletes the row immediately when retention triggers. A grace above zero keeps the row in trash for that many days and surfaces it here for the Admin window where restore is still cheap. ## Where this fits Trash is the second chance retention gives every category before the cleanup pass removes a row for good. It pairs with [policies and limits](/platform/admin/governance/policies-and-limits) — the retention page sets the windows; this page is the recovery view those windows feed. The companion is [legal hold](/platform/admin/governance/legal-hold), which is the only mechanism that beats retention before a row ever lands in trash. # Usage analytics Source: https://tale.dev/docs/platform/admin/governance/usage-analytics Usage analytics is the dashboard that aggregates every billable AI call into a single view of tokens, cost, and request volume. It slices by user, team, role, model, agent, and time so the unexpected line on the bill is traceable to the workload that drove it. Admins and Owners read this page when a bill is unexpected, when leadership wants the rough shape of AI spend, or when a budget alert fires and the next question is _who and what_. ## A worked drill-down Open **Settings > Governance > Usage**. The default view is the last 30 days, org-wide, with the three headline counters — total tokens, total cost in USD, total requests. Switch the breakdown to **By user** to find the heaviest consumers, **By model** to compare an expensive primary against a cheaper fallback, or **By agent** to find the agent driving the load. Each row clicks through to a per-row time series; the chart axis follows the chosen period. ## The dimensions - **User** — every member who has triggered a billable call. Pair with the team or role filter to scope the view. - **Team** — aggregated across team members; useful when budgets are team-scoped. - **Role** — Owner, Admin, Developer, Editor, Member. - **Model** — every model that produced a reply, grouped by provider. - **Agent** — every named agent (the leaderboard sorts by token volume, cost, or request count). - **Time** — daily trend for short windows, weekly for longer windows. ## The cost model Cost is an estimate. Each request lands in the usage ledger with input tokens, output tokens, the model's published price per million tokens, and the wall-clock duration. The dashboard multiplies tokens by price; image generation calls land with a per-image cost the provider returns. The ledger row is the source of truth, and the [audit log](/platform/admin/governance/audit-logs) carries the row's actor and timestamp for cross-reference. ## Budget overlays When [policies and limits](/platform/admin/governance/policies-and-limits) has a budget for a scope, the usage chart overlays the cap as a horizontal line. Hovering a point shows the percentage of the cap consumed and the projected month-end based on the current trend. Crossing the warning threshold paints the chart's series amber; crossing the cap paints it red and surfaces the budget-exceeded events as markers on the time axis. ## Retention of usage rows The usage ledger has its own retention window in [policies and limits](/platform/admin/governance/policies-and-limits). Default is 365 days; shorten it and the historical chart truncates accordingly. The dashboard reflects whatever the ledger holds — there is no archive layer underneath. ## Where this fits Usage analytics is the spend and volume side of the same workload [feedback analytics](/platform/admin/governance/feedback-analytics) reads for quality. Together they answer _is this agent worth its cost_. The companion is [policies and limits](/platform/admin/governance/policies-and-limits) — the page where the budgets this dashboard overlays are configured. # Integrations (admin view) Source: https://tale.dev/docs/platform/admin/integrations Settings > Integrations is the credentials surface for every third-party system Tale talks to on behalf of the organisation. Admins install integrations once; agents, workflows, and the documents pipeline use them everywhere else. This page covers the admin side — what the list shows, how installation and rotation work, what an Admin can scope, and how the surface differs from MCP servers. The feature-level story of each integration (what it does, what scopes it asks for, what an agent can call) lives one tab over on the per-integration pages and in the cross-integration concept page. What follows is the operations surface: install, rotate, restrict, revoke. ![The integrations catalogue showing a grid of connector cards — Slack, Gmail, Google Drive, GitHub, Tavily, and more — each with a Connect action.](/images/platform/integrations-catalog.webp) ## What the list shows Open **Settings > Integrations** to land on the org's installed integrations. Each row names an integration, shows its category (communication, storage, identity, knowledge, source control, commerce, AI), the credential type (OAuth2, API key, app token), and the connection status (connected, pending, error). The list is filterable by category and by status. The catalogue of available integrations sits one click away under **Add integration**. The catalogue currently ships Slack, Microsoft Teams, Discord, Gmail, Outlook, Twilio, Microsoft 365, Google Drive, Confluence, WebDAV, Tavily, GitHub, Shopify, and AI image; the same catalogue is the source the integrations overview documents. ## Installing an integration Pick an integration from the catalogue and click **Connect**. The integration declares the credential type it expects and the scopes it needs; Tale walks the OAuth dance for OAuth integrations and shows a form for API-key integrations. Once the credential lands, Tale verifies it with a no-op call to the upstream system before saving — a failure surfaces as a connection error with the upstream message attached. Some integrations carry sub-options on install. Microsoft 365 lets you pick whether to enable OneDrive sync, SharePoint sync, both, or only single sign-on; GitHub lets you pick the repositories the org grants access to; Slack asks which channels the bot may post in. The sub-options can be changed later from the integration's row without re-installing. ## Updating definitions from the shipped catalogue Each integration's definition — its configuration schema, connector, and icon — is copied into the organisation when the org is created and stays untouched afterwards, so a platform upgrade never changes it behind your back. **Update built-in integrations** in the **Add integration** menu replaces every shipped definition that differs from the current catalogue with the latest version. Credentials, secrets, and custom integrations you added yourself are never touched; the previous version of each replaced definition is preserved on the server so an operator can recover it. ## Rotating credentials To rotate, open the integration's row and click **Rotate credentials**. OAuth integrations walk the dance again with the same scopes; API-key integrations show a field for the new key. The old credential stops working as soon as the new one is verified — there is no overlap window for credentials at the integration level. Reach for rotation on the cadence your security policy mandates, or whenever the upstream system reports the credential is compromised. ## Restricting an integration Beyond the credential, an integration carries two scoping levers under its row: - **Allowed roles.** Restrict which roles' agents and workflows may call the integration. The default is every writer role (Editor, Developer, Admin, Owner); narrowing it is how you keep, say, the Twilio integration out of Member-built agents. - **Allowed teams.** Restrict which teams' agents and workflows may call the integration. Useful when the credential belongs to one team's work (the support team's Slack) and you do not want it leaking into another's. Both levers are enforced at request time, not at install time — changing a lever takes effect on the next call. ## Revoking an integration Click the row, then **Disconnect**. A disconnected integration stops authenticating immediately; agents and workflows that depend on it surface a configuration error on the next call. The row stays in the list with a disconnected badge so the audit trail survives. Reconnecting walks the credential flow again from scratch. ## Slack bot and notifications Slack is two-directional. Beyond the agent calling Slack (posting messages, reading channels), the org can let people talk to an agent from inside Slack and have system events pushed to a channel. Both are configured on the connected Slack row, and both ride the single OAuth credential — no second connection. Each org brings its own Slack app, configured entirely from the Slack row — there is nothing to set on the deployment. When you connect Slack, the row shows a **Set up your Slack app** panel with a ready-to-paste app manifest and the two URLs it references: the Event Subscriptions Request URL (`/api/integrations/slack/events`) and the OAuth redirect URL. The manifest pre-fills the bot scopes, the `app_mention` and `message.im` events, and both URLs, so creating the app at api.slack.com/apps takes a couple of clicks. Paste the app's **Client ID**, **Client Secret**, and **Signing Secret** back into the row, then authorize with OAuth. The signing secret is what verifies inbound events, so the bot stays silent until it is set; inbound messages route back to the right org by Slack workspace. On the connected Slack row an Admin picks **which agent answers Slack** (a mention in a channel or a direct message starts a threaded reply from that agent) and **which channels receive notifications**, with a per-event toggle. The shipped events are workflow failed, workflow completed, and security alerts; a Slack thread maps to one agent conversation, and the Slack author is preserved on it rather than recorded as the system. ## Integrations versus MCP servers Two surfaces let an agent reach beyond Tale. **Integrations** are the first-party, vendor-specific connectors documented here. **MCP servers** are external processes exposing the Model Context Protocol; the org registers them under **Settings > MCP servers** and approves each tool the first time it is called. Reach for an integration when one exists for the target system; reach for [MCP servers](/platform/integrations/mcp-servers) when no integration covers what you need. ## Where this fits Integrations are the credential half of the agent-to-outside-world story; the agent-side half (which tools an agent gets, how it calls them, what the trust boundary looks like) lives under [Agent tools](/platform/agents/tools). The natural next read for a new admin is [Integrations overview](/platform/integrations/overview) — it names every shipped integration grouped by what it does and gives the per-integration setup at a glance. # Members and roles Source: https://tale.dev/docs/platform/admin/members-and-roles Members are the people in your organisation who can sign in to Tale. Roles control what each member can do — read, write, configure, govern. This page is the canonical reference for the six roles and the resource-level permissions each role carries. Six roles cover almost every team Tale ships to. Admins and Owners read this page when they are setting up a team for the first time, when an audit asks who has access to what, or when they need to know whether to give a new hire Editor or Developer. ![The Organization settings page with its Members section listing the workspace owner and an Add member button.](/images/get-started/settings-organization-members.webp) ## Adding a member To add a person to your organisation, open **Settings > Organization**, scroll to the **Members** section, and click **Add member**. Fill in their **Name**, **Email**, and **Role**, and set a **Password** — Tale does not send an email invite, so a password is required to create a new account. (If the email already belongs to a Tale account, no password is asked: the person signs in with their existing credentials and is simply added to this organisation.) On **Add member**, Tale shows the new sign-in credentials **once**, with the reminder to save them now because they won't be shown again. Relay them to the new member out of band — there is no reset email. Anyone who later forgets their password contacts an admin, who can set a new one from the same Members section. Pick the role on the form before you submit; promoting or changing it later is a one-click change in the same Members section. ## The six roles **Owner** has every permission Admin has, plus the one Admin lacks: transferring ownership and deleting the organisation. Most teams have exactly one Owner; some keep two for continuity. **Admin** governs the organisation: members, providers, branding, governance policies, integrations, the audit log. Admins do everything Editor does and everything Developer does, plus the configuration surface. They cannot transfer ownership. **Developer** builds: agents, workflows, integrations, API keys, MCP servers. Developers can read every resource and write to most of them, including governance policies (read-only). Reach for Developer when someone needs the API plane and the integration tooling. **Editor** curates and operates: agents, the knowledge base (documents, customers, products, vendors, websites), the conversation inbox, approvals, the prompt library. Editors can read workflows but not modify them; they can read integrations but not configure them. Reach for Editor when someone runs the day-to-day product work without touching the API or integration plane. **Member** runs: chat, browse the knowledge base, read conversations and approvals others have assigned to them. Members write only to message feedback (thumbs up / down). Reach for Member as the default — most users in most organisations are Members. **Disabled** has no permissions. Use it to revoke access without deleting the account; transcripts and audit history stay intact, and re-enabling restores the previous role. ## The permission matrix | Resource | Owner | Admin | Developer | Editor | Member | Disabled | | --------------------- | ----- | ----- | --------- | ------ | ------ | -------- | | Agents | R / W | R / W | R / W | R / W | R | — | | Documents | R / W | R / W | R / W | R / W | R | — | | Products | R / W | R / W | R / W | R / W | R | — | | Customers | R / W | R / W | R / W | R / W | R | — | | Vendors | R / W | R / W | R / W | R / W | R | — | | Projects | R / W | R / W | R / W | R / W | R | — | | Websites | R / W | R / W | R / W | R / W | R | — | | Conversations | R / W | R / W | R / W | R / W | R | — | | Conversation messages | R / W | R / W | R / W | R / W | R | — | | Approvals | R / W | R / W | R / W | R / W | R | — | | Workflow executions | R / W | R / W | R / W | R | R | — | | Workflow processing | R / W | R / W | R / W | R | R | — | | Integrations | R / W | R / W | R / W | R | R | — | | OneDrive sync configs | R / W | R / W | R / W | R | R | — | | Prompt templates | R / W | R / W | R / W | R / W | R | — | | Audit logs | R / W | R / W | R / W | R / W | R | — | | Governance policies | R / W | R / W | R | R | R | — | | Message feedback | R / W | R / W | R / W | R / W | R / W | — | | MCP servers | R / W | R / W | R / W | R | R | — | R = read, W = write, — = no access. The matrix is the authoritative description of what each role can do across the resources Tale tracks; the rows are the same set the in-product permission system uses at request time. ## The Settings surface and the menu Members, Editors, and Disabled users do not see the configuration surface — only their own personal settings. Developers see the organization settings but not the governance sub-tree (except read views). Admins and Owners see everything. The settings menu is grouped into **Personal** (Account, Preferences, Environment — every role), **Organization** (the Members section, Teams, AI providers, Branding, Governance, and the rest — Admin-and-Owner, with Developers seeing a subset), and **Development** (the API and data-residency surface). Governance is an item inside the Organization group, not a group of its own, and it needs Admin access. ## Edge cases **Transferring ownership** requires an existing Owner to nominate a current Admin or Owner; the new Owner role takes effect immediately. The previous Owner becomes Admin unless explicitly downgraded. **Last Admin warning.** The Members section warns when removing or downgrading the last Admin or Owner. The action is allowed — Tale does not lock you out — but you should keep at least two Admin-or-Owner accounts for continuity. **Resetting 2FA** is on the member's row in the Members section. Resetting clears the second factor; the next sign-in re-enrolls. ## Where this fits Roles are the access surface every other admin page touches: SSO authenticates them, API keys belong to them, audit logs name them, governance policies scope behaviour by role. The next page worth reading depends on what you are doing next. If you are wiring sign-in to your identity provider, [authentication](/self-hosted/configuration/authentication) covers the four sign-in modes. If you are scoping access by team rather than by role alone, [Teams](/platform/admin/teams) covers the per-team scoping layer. # Admin Source: https://tale.dev/docs/platform/admin/overview Admin is the configuration plane of Tale. It covers the people who can sign in, the teams that group them, the AI providers behind every reply, the API keys that let external code talk to the org, the third-party integrations agents reach through, and the branding the rest of the org sees. Only Admins and Owners see the full Admin menu; Developers see a subset, and other roles do not see it at all. These pages describe what each setting does and what it changes about the running product. Most are read once during setup and revisited when something changes — a new hire, a rotated key, a new provider. The role-and-permission story behind the whole menu lives in [Members and roles](/platform/admin/members-and-roles); start there, because every other Admin page references the role names it defines. ## Configuration areas The six roles and the resource-level matrix that says who can read, write, configure, and govern. Group members into teams that share agents, prompts, and integrations. Every agent the org has, and where an Admin steps in when one needs governance. Connect the OpenAI-compatible providers behind every reply and pick which models the org may use. Shared credentials that agents and tools draw on without each member holding the secret. Install and rotate the credentials behind Slack, Gmail, Outlook, Google Drive, GitHub, Shopify, and more. Wire sign-in to your identity provider with SAML or OIDC. Mint and scope the keys external code uses to reach Tale's REST API. The name, logo, and colors the rest of the org sees. Require a second factor for sign-in and manage enrolment across the org. The in-product record of what shipped and when. Audit logs, policies and limits, guardrails, analytics, retention, and legal hold. ## Where this fits Admin is the surface every other tab assumes. Chat resolves a model through the providers configured here; agents call tools through the integrations configured here; the prompt library and the inbox respect the team boundaries configured here. The natural first read is [Members and roles](/platform/admin/members-and-roles) — every other Admin page references the role names it defines. # AI providers Source: https://tale.dev/docs/platform/admin/providers Settings > AI providers is the surface where Tale meets the models it serves. A fresh org ships with one provider connected — **OpenRouter**, whose single key reaches chat, vision, embedding, transcription, speech, and image models — and Admins add, edit, or retire providers from here. Every reply Tale streams is routed through a model resolved on this page; touching it changes what the rest of the product can do. ![The AI providers settings page listing one connected provider, OpenRouter, with its base URL and a count of 52 models, beside an Add provider button and the model-catalog sync controls.](/images/get-started/settings-providers.webp) ## What the list shows Open **Settings > AI providers** and you land on the providers the org has connected. Each row names the provider and shows whether its API key is configured. Clicking a row opens the provider's drawer: its base URL and key, its **Default Models**, and the **Models** list itself — searchable, with the capability tags that decide where each model can be used. The drawer is where all the per-provider work happens. The list view is deliberately thin; the depth is one click in. ## Adding a provider Click **Add provider**. **Start from a known provider** picks OpenAI, Anthropic, or OpenRouter and fills in the provider name and base URL — the only thing left to add is your API key. Editing the name or base URL by hand switches the picker back to **Custom**, the manual path: a provider is a **base URL** plus an **API key** — a direct vendor's own endpoint, OpenRouter (`https://openrouter.ai/api/v1`) for the widest catalog, or a local Ollama or vLLM server on your network. The key is stored encrypted and used only to call that provider. Once the credential lands, populate the model list: **Fetch models** pulls the list the provider's API reports, **Add model** declares one by hand, and — once the org's model catalog has synced — picking a model from the catalog inside that dialog fills its ID and known capabilities (context window, pricing, reasoning) instead of typing them. No model is callable until it is in the provider's list with the right capability tag. For OpenAI, Anthropic, and OpenRouter, the base URL stays locked to the published endpoint even after the provider is created — open the row's drawer, click **Edit** under **General**, and the field shows read-only with an **Override base URL** button beside it. Reach for the override only to point that provider's slug at a compatible proxy or regional mirror; every other provider's base URL is editable directly, no override needed. ## The model list and capability tags Each model carries one or more capability tags — **Chat**, **Vision**, **Embedding**, **Transcription**, **Text-to-speech**, **Image generation**, **Image edit**. The tags are load-bearing: they decide which pickers a model appears in and which platform capability may call it. A model with no matching tag never appears where that capability is needed. **Hidden from model pickers** takes a model out of the chat composer and agent model selection while leaving it fully usable by agents and workflows that already reference it. That is how a superseded or deprecated version retires without breaking the agents bound to it. ## Default models The **Default Models** card names which model each capability uses when nothing more specific is bound — the chat default for new chats and new agents, plus the vision, embedding, image-generation, and transcription defaults the background services use. Changing a default affects new objects only; existing chats and agents keep the model they were bound to. Reach for the defaults when you roll out a new generation of model across the org without re-editing every agent. ## Keeping the catalog fresh Two controls keep the catalog current without hand-editing. The **Model catalog** card refreshes each model's capabilities — pricing, context window, reasoning, vision — from OpenRouter's public catalog daily. The **Weekly auto-sync of provider config** toggle merges newly released flagship versions into the org's provider config once a week, hides superseded ones, and leaves any field you customized untouched. ## Where this fits Providers are the bottom of the stack — every agent, every chat, every workflow step that produces text resolves through them. The catalogue of what each provider ships and which tags they carry lives in [Models](/platform/models); the file-based form of the same configuration lives under [Configuration → providers](/self-hosted/configuration/providers); and [Agent concepts](/platform/agents/concepts) covers how the model knob fits into the four-knob model an agent is built from. # Teams Source: https://tale.dev/docs/platform/admin/teams A team is a named group of members that shares access to agents, prompts, projects, integrations, and conversations. Where roles define what a person _can_ do, teams define which slice of the org's data that person works in. Most orgs end up with a handful of teams — support, sales, ops — and most of the day-to-day permission decisions land on the team boundary, not the role boundary. Admins manage teams under **Settings > Teams**. This page is the reference for what a team owns, how membership works, and how the team boundary interacts with the role-based permissions documented under [Members and roles](/platform/admin/members-and-roles). Read it once when you stand up the org's teams; come back when you reorganise. ![The Teams settings page listing three teams — Growth, Platform engineering, and Customer success — each with one member and the date it was added, beside a Create team button.](/images/platform/settings-teams.webp) ## What a team owns A team holds membership and a set of resources scoped to it. The resources are: - **Agents** — agents created with a team scope are visible and editable only by members of that team. Org-wide agents stay visible to everyone with the right role. - **Prompts** — saved prompts with `Team` visibility appear only to that team's members. Personal prompts stay private to their owner; Global prompts are visible org-wide. - **Projects** — projects can be assigned to a team; the team's members inherit project access without being added one by one. - **Integrations** — integrations restricted to certain teams (under the **Allowed teams** lever on **Settings > Integrations**) only appear in pickers for those teams. - **Conversations** — customer-channel conversations can be routed to a team; the inbox filter respects the team scope. A resource without a team scope stays visible to everyone whose role allows it. Teams are an _additive_ scoping layer — they narrow visibility, never widen it. ## Creating a team Open **Settings > Teams** and click **Create team**. Give the team a name (`Support`, `Sales`, `Operations`) and an optional description; the name appears everywhere the team shows up — pickers, badges, the prompt library tabs, the integration allowed-teams field. Saving creates an empty team you can fill with members from the team's row. The team's row carries three sub-views: **Members** (who is in the team), **Resources** (what the team owns), and **Settings** (the team's name, description, and lifecycle). The Resources view is the easiest way to see what a team can reach into; it doubles as the audit surface when someone asks why a team can see a particular agent. ## Adding and removing members Open the team's row and click **Add members**. The picker lists the org's members; checking one adds them to the team. A member can belong to multiple teams; their access is the union of every team they are in plus their role's org-wide reach. Removing a member from a team strips the team-scoped visibility on the next request; in-flight chats finish, but the next thread does not see the team's resources. ## Team versus role The role decides what a person can do; the team decides what they can do it to. A Member-role user in the Support team can read the support team's agents but cannot edit them; a Developer-role user in the Support team can read and write the support team's agents but cannot see Sales's. Teams never grant capabilities the role lacks; roles never widen visibility past the team scope. When you need a permission decision the existing roles and teams cannot express, the next lever is a governance policy — see [Members and roles](/platform/admin/members-and-roles) for how policies attach to roles, and the governance section for the policy fields themselves. ## Deleting a team Click the team's row, then **Delete team**. Deletion is hard-stop — the team is gone, every team-scoped resource it owned moves to org-wide visibility, and members lose the team-scoped slice of their access. There is no undo; orphaned resources stay reachable by everyone whose role allows them, which is rarely the right outcome. Reach for delete when a team is genuinely retired, not when it is reorganising. ## Where this fits Teams are the scoping layer right below roles — roles say _what_, teams say _where_. The natural next read depends on the resource you are scoping: [Prompt library](/platform/workspace/prompt-library) for how prompts attach to teams, [Integrations (admin view)](/platform/admin/integrations) for the allowed-teams lever, and [Projects](/platform/projects/overview) for project-to-team assignment. # Token sources Source: https://tale.dev/docs/platform/admin/token-sources Settings > Token Sources is for the case where one static API key is not enough: instead of binding a bring-your-own-key agent to a single secret, you point it at an external broker that returns a _pool_ of credentials. The agent picks one token per run and, if that token comes back rate-limited or expired, fails over to a different one from the same pool — up to three attempts before the run fails. It is the rotation layer under a BYO [external agent](/platform/agents/external-agent), nothing more: managed agents keep using the org gateway and ignore this page entirely. This page covers the UI — what the list shows, the fields when you add a source, how a source binds to an agent, and what rotation actually does at run time. The broker's auth secret is write-only here; its file and environment-variable forms live one tab over under the [self-hosted configuration](/self-hosted/configuration/environment-reference) reference. ## What the list shows Open **Settings > Token Sources** and you land on the table of sources the org has configured. Each row names the source, shows its broker endpoint, and shows the target environment variable the rotation engine injects the chosen token under (for a Claude Code agent that is usually `CLAUDE_CODE_OAUTH_TOKEN`). Search filters by name or endpoint; the **···** menu on a row edits or deletes it, and selecting rows reveals a bulk-delete bar. A source is config only — it stores _how_ to reach the broker and _how_ to read its response, never the tokens themselves. Tokens are fetched fresh from the broker each time an agent run starts, so the list never goes stale against the broker's current pool. ## Adding a source Click **New token source** and fill the side panel. The form is grouped into four sections: - **Identity** — a `slug` (lowercase, stable; it names the config file and the secret) and a display name. - **Connection** — the broker **endpoint** with its HTTP method, and how Tale authenticates _to the broker_: none, a bearer token, or a custom header. For bearer or header you enter the broker secret. The secret is write-only — it is never returned to the browser, so on edit the field shows blank and leaving it blank keeps the stored value. - **Response mapping** — how to read the broker's JSON. `Tokens path` is a JSONPath to the array of tokens (e.g. `$.tokens`); `Token field` names the property holding each token. The optional `Status field` / `Status active value` filter out inactive tokens, and `Expiry field` (an ISO timestamp or epoch seconds/ms) drops already-expired ones before the pool is used. - **Binding** — the **target environment variable** the token is injected under and the **selection strategy**: `random` (the default, picks uniformly per run) or `first` (deterministic). Before saving, press **Test broker** in the Response mapping section: Tale fetches the broker server-side with the draft config and previews the mapping — how many usable tokens the paths yield, how many items were dropped as inactive, expired, or missing the token field, and the next expiry — so a wrong JSONPath surfaces in the form instead of at agent runtime. Saving validates the config, writes it, and makes the source immediately selectable on the agent Environment tab. ## Binding a source to an agent A token source does nothing until an agent draws from it. Open the agent's **Environment** tab, add a row, and change its type from **Value** / **Secret** to **Token source** — a second dropdown then lets you pick which source. The row's variable name is the env var the chosen token lands in, overriding the source's own default for that agent. Binding only takes effect for bring-your-own-key agents. A managed agent authenticates through the org gateway, so a token-source row on one is ignored with a warning rather than silently changing how the agent is billed. ## What rotation does at run time When a bound BYO agent starts, Tale fetches the broker pool, filters out inactive and expired tokens, and injects one pick. If the run ends in a rotatable failure — a rate limit (`429`/`529`) or an auth error (`401`/`403`) — Tale swaps in a different token from the pool and re-runs, up to three tokens total, as long as enough of the run window remains. An auth error is cut short early rather than left to storm the provider's internal retries. If every tried token fails the same way, the run fails fast with a clear error instead of looping. If the broker is unreachable, returns malformed JSON, or yields no active, unexpired token, the run fails immediately — there is no silent fallback to a static key, because a BYO agent has none. ## Removing a source Open the **···** menu and choose **Delete**, or select rows and use the bulk-delete bar. Deleting removes the config and its stored secret. Any agent still bound to the deleted source fails its next run with a configuration error rather than falling back, so re-point or remove the binding on the agent's Environment tab first. ## Where this fits Token sources sit beside [AI providers](/platform/admin/providers) as the second way Tale acquires model credentials: providers are the managed, gateway-routed path; token sources are the BYO, broker-rotated path for agents that bring their own keys. The natural next read is the [external agent](/platform/agents/external-agent) page for how a BYO agent is built, and the [environment reference](/self-hosted/configuration/environment-reference) for the `TALE_TOKEN_SOURCE_` form of the broker secret when you configure a source from files instead of the UI. # Two-factor authentication Source: https://tale.dev/docs/platform/admin/two-factor-authentication Two-factor authentication adds a second proof of identity on top of the password — a six-digit code from an authenticator app, or a WebAuthn passkey. Tale ships TOTP (time-based one-time passwords) compatible with Google Authenticator, 1Password, Authy, and any other app that follows the standard, plus passkeys for a phishing-resistant alternative. The page covers per-user enrolment, passkeys, the backup codes that recover an account when the phone is gone, the org-wide enforce policy, and the admin reset for a locked-out member. Two-factor is optional by default. Admins can require it for the whole organisation with a grace window so members have time to enrol. ## Per-user enrolment To turn 2FA on for your own account, open **Account > Security**. Click **Enable two-factor**, confirm your password, and scan the QR code with an authenticator app. Enter the six-digit code the app shows to verify the secret was captured, then save the backup codes the next screen presents. The codes show once — download or copy them before clicking **Done**. The same screen carries **Disable** and **Regenerate backup codes**. Disabling clears the second factor; regenerating invalidates every previous backup code. Both actions require the account password as a confirmation. ## Backup codes Backup codes are single-use strings the platform mints when 2FA is enabled or regenerated. Each one substitutes for the authenticator code on a single sign-in — useful when the phone is lost, the authenticator is uninstalled, or you are stuck somewhere without the device. The platform watches the remaining count and surfaces a low-balance banner when only a few codes remain; the banner links straight to the regenerate flow. Treat backup codes like passwords. Store them in a password manager or print them and lock them away. Anyone who has both your password and a backup code can sign in as you. ## Passkeys A passkey is a WebAuthn credential — Face ID, Touch ID, Windows Hello, or a hardware security key — that signs a per-login challenge instead of producing a typed code. The credential is bound to the site's origin, so a look-alike phishing domain gets nothing to replay; that makes a passkey phishing-resistant in a way TOTP is not, and it satisfies an enforced two-factor policy exactly like TOTP does. To register one, open **Account > Security** and click **Add a passkey**. Give the credential a name you will recognise later, then pick the **Authenticator type**: **Any (recommended)** lets the browser offer everything available, **This device (Face ID, Touch ID, Windows Hello)** narrows the ceremony to the built-in authenticator, and **Security key or phone** narrows it to a roaming one. The browser runs the registration ceremony from there. Each entry in the same list carries a **Remove** icon button for revoking your own credentials; it asks you to confirm before the passkey is removed. A registered passkey works at three doors. On the login screen, **Sign in with a passkey** signs you in without typing the password — the credential is itself strong proof. On the verification screen after a password login, **Use a passkey instead** replaces the six-digit code. And on the enrolment screen an enforced policy routes unenrolled members to, **Register a passkey instead** sits next to the TOTP setup — a member who registers only a passkey, never TOTP, passes the policy. When a member loses a device with a passkey on it, an Admin revokes the credential: open **Settings > Organization**, click **Edit member** on the member, and remove the credential from the **Passkeys** section of the dialog. Tale deletes the credential and ends every active session of that member, so a lost or stolen authenticator can't keep a session alive. Registration, self-removal, admin revocation, and every passkey sign-in land in the audit log (`passkey_added`, `passkey_removed`, `passkey_revoked_by_admin`, `passkey_sign_in`). ## The enforce-for-org policy Admins can require two-factor for every password-authenticated member of the organisation. Open **Settings > Governance > Security & Monitoring** and, under **Two-factor authentication**, toggle **Require two-factor authentication**. The policy carries a grace period (in days) that gives each member time to enrol from their first sign-in under the policy; set it to zero for immediate enforcement. ![The Security and Monitoring governance page showing login-attempt limit fields and the password-policy character-class requirements; the two-factor policy is further down the same page.](/images/platform/governance-security-monitoring.webp) | Field | Type | Required | Description | | --------------------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | Require two-factor authentication | Toggle | yes | Off keeps 2FA optional for every member; on turns the policy on. | | Grace period (days) | Integer | yes | Days from a member's first signed-in moment under the policy before enrolment is required. Zero means immediate. | | Exempt SSO-only users | Toggle | no | When on, members whose only account is a federated identity rely on the upstream IdP for MFA. | A member inside the grace window sees a count-down banner in the app pointing them at the enrolment flow. Once grace expires, the next sign-in routes through the enrolment screen and the member cannot continue until they have enrolled. ## Admin reset for a locked-out member When a member loses their phone and their backup codes, an Admin clears the second factor on their account. Open **Settings > Organization**, click **Edit member** on the member, and click **Reset two-factor** in the dialog. Tale disables 2FA for the account and ends every active session, so the member re-enrols on their next sign-in. The reset is recorded in the audit log under `2fa_reset_by_admin`. Reach for it as a recovery action — the member should re-enrol immediately once they are back in. ## Where this fits Two-factor sits one layer above the password — same login screen, second step. Pair it with [members and roles](/platform/admin/members-and-roles) (the admin who resets the second factor is the same admin who manages the account), with [policies and limits](/platform/admin/governance/policies-and-limits) (the enforce policy lives in the governance surface), and with [audit logs](/platform/admin/governance/audit-logs) (every enrolment, disablement, and admin reset lands there). # Agent folders Source: https://tale.dev/docs/platform/agents/categories Agents are grouped by folders, and a folder comes from the agent's id: an agent whose id is `github/review-pull-requests/pr-reviewer` files under a `github/review-pull-requests` folder wherever agents are listed. Folders are an organisational sorting tool, not a permission boundary — who can use an agent is the **Access** section on its **General** page, unchanged by where it is filed. ![The agents list showing the chat folder's agents — Assistant and Automation Assistant — each with a Type badge, default model, and tool count.](/images/platform/agents-list-expanded.webp) ## File an agent into a folder Foldered ids come from the platform, not the create dialog. The dialog's **Name** field takes a flat id — lowercase letters, numbers, hyphens, and underscores, no `/` — so an agent you create there lands unfiled at the top level. The folder prefix (`chat/`, `github/review-pull-requests/`) is reserved for agents the platform ships or installs: builtins arrive pre-filed, and installing an [automation](/platform/automations/concepts) files its agents under the folder their id names. An id can't change later, so the folder is fixed when the agent is created. The display name is independent; rename the agent freely without moving it. In the **Agents** list, folders render as collapsed rows with an agent count — click one to expand it, and the breadcrumb tracks where you are. The builtin agents ship pre-filed: the general assistants under `chat`; automation-installed agents file under their automation's folder. ## Agents that arrive with an automation Installing an [automation](/platform/automations/concepts) files its agents like any others — the PR Creator and PR Reviewer from the Resolve GitHub issues bundle land in the same list, in the folder their id names. There is no separate agent store to browse: the [Automations catalog](/platform/automations/catalog) is where bundled agents come from, and the list is where they live afterwards. The chat picker does not group by folder — it is a searchable list with **Auto** on top, showing every agent that is enabled and visible in chat, with coding agents under their own **Coding agents** section. ## When to reach for it | Use folders when… | Use team access when… | | ----------------------------------------------- | ------------------------------------------------------ | | The agents list is getting long and needs order | An agent must only be usable by one team | | Departments each own a set of agents | You are drawing a permission boundary, not a directory | ## Where this fits Folders are the lightest available grouping for agents — they sort the list and the catalog, nothing more. Larger separations live elsewhere: [Project agents](/platform/projects/project-agents) scope an agent to a Project, and [Policies and limits](/platform/admin/governance/policies-and-limits) govern what any agent may spend or do. # Agent concepts Source: https://tale.dev/docs/platform/agents/concepts An agent is the unit Tale reaches for when the same question is going to come back. It is the four-knob combination of instructions, knowledge, tools, and a model — the four things you change to make the agent behave differently. Editors and Developers build them; Members and other roles run them. This page hands you the mental model the rest of the section assumes. Read it once before you build your first agent; come back to it when you can't remember whether a behaviour you want to change lives in the instructions, the knowledge, the tools, or the model. ## The four knobs **Instructions** are the system prompt — the prose that frames every reply. Keep instructions short, opinionated, and concrete; long instructions get diluted in long conversations. Specify the voice, the constraints, and the refusal cases. **Knowledge** is what the agent can retrieve from the org's knowledge base. A retrieval mode decides whether the agent searches on demand, has relevant chunks injected into every reply, does both, or neither — and scope switches decide whether team documents, organization documents, and the agent's own uploads are searchable. Knowledge outside those scopes is invisible to the agent — there is no implicit pull from everything the org owns. **Tools** are what the agent can do beyond replying with text. The agent's **Tools** tab is a per-tool checklist grouped by category — customer and product data, files, workflows, web search, code execution, and more. Toggle each tool individually; every tool you grant widens the trust boundary, so keep the list short. **Model** is the LLM behind every reply. Models are an ordered list: the first entry is the primary, and the rest are fallbacks Tale tries in order when the primary is unavailable. Switching the model does not re-train anything — the agent's other three knobs are the model's "memory" of the job. ```mermaid flowchart LR I[Instructions] --> A((Agent)) K[Knowledge] --> A T[Tools] --> A M[Model] --> A A --> R[Reply with citations] ``` ## Skills as a bundle A skill packages instructions — and optionally scripts and reference files — into a reusable bundle you bind to an agent. Reach for a skill when the same pattern appears across multiple agents: a writing voice, a calculation, a multi-step task. Skills compose with the four knobs; an agent can bind up to ten and reads each one at runtime. The skills page covers the trade-off between a skill and inline instructions in detail: see [Agent skills](/platform/agents/skills). ## Putting it together — a support-triage agent A first useful agent is the support-triage one: it reads the inbound question, answers what it can, and escalates the rest. The four knobs: - Instructions: a one-paragraph voice plus three explicit refusal cases. - Knowledge: retrieval on demand over the product documentation; nothing agent-specific uploaded. - Tools: web search and the conversation tools. No code execution. - Model: a capable primary with a cheaper fallback next in the list. The conversation then flows: user message → instructions frame the reply → knowledge retrieval finds the relevant chunks → tools fill the gaps → the reply lands with citations. Escalation to a specialist is not a tool toggle — it follows delegate relationships between agents. See [Agent workers](/platform/agents/delegation). ## When to reach for it A single agent is the right shape when the conversation stays in one domain and one voice. Reach for a [workflow](/platform/automations/concepts) when the work is multi-step and you want approvals or scheduling in between; reach for a raw chat (no agent) when you are exploring an answer yourself and the model's defaults are fine. | Use … when | Agent | Raw chat | Workflow | | ---------------------------------------------- | ----- | -------- | -------- | | Same question recurs | ✓ | | | | The voice or constraints matter | ✓ | | | | You need approvals or scheduling between steps | | | ✓ | | You are exploring an answer one time | | ✓ | | ## Build one The four knobs are what every Tale agent is made of: change one of them and you have changed the agent's behaviour, change three and you have made a new product. The natural next read is [Build your first agent](/tutorials/editor/first-agent-end-to-end) — it walks the four knobs end to end on a fresh instance. # Conversation starters Source: https://tale.dev/docs/platform/agents/conversation-starters A starter is a short suggested prompt the agent shows on an empty chat screen. Tap one and the text drops into the composer; the user edits if they want, then sends. Starters are the agent author's curated entry points into what the agent is for — this page is the author side; how they render to the user is [Starters and prompts](/platform/chat/starters-and-prompts). ![The agent editor's Starters tab showing four English conversation starters with drag handles, reorder arrows, and remove buttons.](/images/platform/agent-editor-starters.webp) ## Add and order starters Open the agent and switch to the **Starters** tab. Each starter is one prompt of up to 200 characters; **Add starter** appends a row, up to four per agent — leave the list empty to show no suggestions. Order matters because it is the order users see: drag a row's handle or use the arrows to move it, and remove one with the × on its row. Click **Save** — starters ship with the agent's configuration like every other setting. Write starters the way a user would actually ask: concrete, first person, inside the agent's domain. Four vague prompts read worse than two sharp ones. ## Translate them Each starter has a default version (the tab marked **default**) and an optional translation per locale. A locale tab still missing its version is flagged **untranslated**, and users in that locale see the default text. Switch to a locale tab to type translations by hand — translations override the existing rows; the list itself (count and order) is owned by the default locale. **Auto-translate** on a locale tab fills in the missing versions in one step. The results are saved as ordinary editable strings, so adjust them afterwards where the machine phrasing misses your voice; if translation fails, a toast says so and the defaults stay in place. ## Where this fits Conversation starters are the smallest surface in the agent area — a few sentences each, but they decide whether the empty chat screen looks inviting or blank. The page worth pairing this with is [Starters and prompts](/platform/chat/starters-and-prompts), which shows how they render to the user; the rest of the agent's behaviour lives in [Agent concepts](/platform/agents/concepts). # Create an agent Source: https://tale.dev/docs/platform/agents/create This tutorial walks from an empty **Create agent** dialog to an agent you publish and use. The result is a working agent that knows its domain, has the tools to act on what it reads, and is reachable from any chat in your org. About fifteen minutes if you have a model provider already configured; longer if you also have to set one up. The tutorial uses a support-triage agent as the running example — the same one [Agent concepts](/platform/agents/concepts) introduces. Substitute your own domain freely; the steps do not depend on the example. ## Before you begin Make sure two things are in place: - A model provider is configured under **Settings > Providers**. Cloud users get one by default; self-hosted operators follow [Configuration → providers](/self-hosted/configuration/providers). Without one the dialog stops you: an agent needs a model to run. - You hold the Editor role or higher in this org. Check your member row under **Settings > Organization** if you are not sure. ## Step 1 — Create the agent Open **Agents** in the sidebar and click **Create agent**, then pick **Blank** (the menu also offers **From template** and **Upload file** for importing agent JSON). The dialog asks for four things: a **Name** — the unique id used in links and the API, which you can't change later — use lowercase letters, numbers, hyphens, and underscores only, e.g. `seo-writer` — a **Display name** teammates see in chat, a **Description**, and the **Model** list. The first model is the default and the rest are fallbacks; drag to reorder or add more anytime. Click **Continue** and the editor opens on the **General** tab. ![The agents list with the chat folder expanded, showing the Assistant and Automation Assistant rows with their default models and tool counts.](/images/platform/agents-list-expanded.webp) ## Step 2 — Write the instructions Open **Instructions & models**. The **System instructions** field is plain markdown, with **Browse prompts** to start from the org's prompt library and template variables that resolve at runtime. Three pieces of advice from the field: - **Open with the voice.** One paragraph naming who the agent is, who it answers to, and what tone it strikes. The model treats this as the strongest signal. - **Name the refusal cases explicitly.** Three or four sentences that say what the agent declines to do and what it says when it declines. - **Resist specifying every behaviour.** Long instructions get diluted in long conversations. If a behaviour belongs in code, lean on a tool; if it belongs in data, lean on knowledge. The same tab holds the model list you set in the dialog — the first model is the primary, and each model below is the next fallback when the one above is unavailable. ![The Instructions & models tab of the agent editor, showing the system instructions field with locale tabs and an ordered list of five models with reorder controls.](/images/platform/agent-editor-instructions.webp) ## Step 3 — Scope its knowledge Switch to the **Knowledge** tab. Pick a **Retrieval mode** — **Tool** lets the agent search on demand, **Context** injects relevant knowledge into every response, **Both** does both, **Off** disables the knowledge base. Then scope what is searchable: **Include team documents**, **Include organization documents**, and **Agent documents** you upload for this agent alone. Bind the smallest useful set — everything you include competes for retrieval on every question. ![The agent editor's Knowledge tab with Tool picked as the retrieval mode, the team and organization document toggles both on, and the organization documents list where every file carries an Indexed badge.](/images/platform/agent-editor-knowledge.webp) ## Step 4 — Grant the tools Switch to the **Tools** tab. Tools are individual checkboxes grouped by category — customers, products, files, workflows, and more — plus a **Web search** mode selector at the top. Grant what the agent needs and leave the rest off; every toggle widens the trust boundary. ![The agent editor's Tools tab scrolled to the category cards, with Knowledge at three of four tools checked and Files at seven of seven, while Conversations, Discussions, Analytics, and Tasks & projects have none granted.](/images/platform/agent-editor-tools.webp) **Run code** (under **System**) executes scripts in a sandbox and is governed by the org's [run-code policy](/platform/admin/governance/run-code-policy) — the checkbox grants the tool, the policy decides what a run may do. ## Step 5 — Make it visible and try it Back on **General**, flip **Visible in chat** on and click **Save**. A toast confirms **Agent saved**. Open a new chat, pick the agent from the picker, and send a message that exercises the knowledge and tools you granted. If the agent answers the way you wrote it to, you are done; if it does not, the **History** button at the top right of the editor shows every saved version and lets you compare or restore. ## Troubleshooting - **Saving fails with a model warning.** The agent has no model set — add one on the Instructions & models tab before saving. - **Agent does not appear in the chat picker.** Confirm **Visible in chat** is on; when it is off the agent can only be reached through delegation. If it is on, check the **Access** section — an agent assigned to a team is only usable by that team. - **Replies ignore the knowledge.** The retrieval mode may be **Off**, the scope toggles off, or the document not yet **Indexed** — open it from [Documents](/platform/knowledge/documents) to check. - **A tool call is refused at runtime.** A governance policy is gating the tool: the agent definition allows it, the runtime refuses. Check [Policies and limits](/platform/admin/governance/policies-and-limits). ## Where this gets used Creating one agent is the moment the rest of the platform starts to feel like Tale rather than a generic chat. The natural next walk is [Agent with knowledge](/tutorials/editor/agent-with-knowledge) — same shape, but binds a folder of documents and exercises the citation pipeline end to end. To see an agent hand a sub-task to a spawned worker, [Hand work to a worker](/tutorials/editor/delegate-between-agents) is the walk. # Agent workers Source: https://tale.dev/docs/platform/agents/delegation Spawning is the move you make when one task deserves its own focused context: open-ended research, bulk extraction, drafting a long document. The agent you chat with composes a **worker** on demand — a name, task instructions, an optional operating method, and a tool grant — runs it, and folds the result back into its reply. Workers are ephemeral: they exist for one job, and their run is recorded as a **job card** in the chat. This page hands you the mental model for when a worker is the right shape and how the platform keeps it bounded. The end-to-end walk lives in [Hand work to a worker](/tutorials/editor/delegate-between-agents). ## How a job runs When the agent calls **spawn_agent**, Tale resolves the worker's capabilities, starts a fresh child conversation, and runs the worker non-interactively: it sees only the task input the agent sent (not the whole chat history), tracks its progress on a live checklist, and its final message comes back to the agent as the result. The chat shows a job card with the worker's name, live progress, terminal status, and an expandable transcript of everything it did. Workers cannot talk to the user. If a worker needs input only a human can give, it says so in its result and the agent asks you — questions always come from the agent you actually talk to. ## Capabilities are a subset, always A worker can hold at most what its spawning agent holds. Three layers decide the effective grant: - **Org configuration** — the agent's own tools, skills, and integrations, as configured by your admins. Nothing new to manage per worker. - **The per-job grant** — the agent picks the smallest set from its own capabilities for this task (fewer tools = a more focused worker). - **Platform exceptions** — a few tools never transfer, most importantly the ask-the-user tool: a worker's questions must flow through the agent, so answering never dead-ends. Workers also cannot spawn workers. One exception runs the other way: every worker can always list and read the thread's files (uploads, generated outputs) — writing files or running code stays an explicit grant. Anything requested outside those bounds is silently skipped and reported — the job card shows what was narrowed away, and the agent adapts (for example, telling you an integration needs connecting). ## Operating methods For open-ended work, the agent can grant a **methodology skill** as the worker's operating method — `web-research` ships built-in: live planning on the checklist, per-question search budgets, and a cited deliverable. Methodologies are skills, so admins govern them the same way as every other skill. ## Timeouts and budget A worker runs inside its agent's remaining turn budget and cannot extend it; if time runs out, the job ends `timed out` with its partial progress visible on the card. Token spend rolls up to the spawning agent, so monthly agent budgets and org budget rules see job spend as the agent's own. Admins cap concurrent jobs per organization under **Governance → agent_jobs** (default 10). ## When to reach for it | Use … when | Worker | Single agent | Workflow | | ------------------------------------------------------- | ------ | ------------ | -------- | | One sub-task benefits from an isolated, focused context | ✓ | | | | The agent can answer well inline | | ✓ | | | Work has explicit stages with approvals between them | | | ✓ | The cost of a worker is one extra run; the benefit is a clean context with exactly the right capabilities for the sub-task, and a job card that shows the user what happened. When the stages are fixed and you want approvals or scheduling between them, a workflow is the right shape instead. # External agents Source: https://tale.dev/docs/platform/agents/external-agent Tale ships built-in **external agents** — **Claude Code**, **Cursor**, **OpenCode**, **Hermes Agent**, **Gemini CLI**, **Codex**, **Pi**, and **OpenClaw** — whose whole turn runs inside an isolated sandbox. Instead of the normal chat loop, your message is handed to that coding agent, which lives in a fresh container, edits files, runs commands, and reports back. You talk to it directly in the chat, and it keeps the same working directory and conversation across turns, so a follow-up like "now add a test for that" continues where it left off. It is the same idea as running such a tool on a remote machine, except the machine is a managed sandbox the workspace controls. This page covers how to use it, what the sandbox can and cannot reach, and how it is billed. ## Talking to a coding agent Pick **Claude Code**, **Cursor**, **OpenCode**, **Hermes Agent**, **Gemini CLI**, **Codex**, **Pi**, or **OpenClaw** in the chat picker and describe a task in plain language — "write a small Python CLI and test it", "clone this repo and fix the bug in issue #42". The agent works inside its sandbox: it plans, writes files, runs shell commands, and installs packages as needed, then replies with what it did. While it works you see a thinking indicator; the reply lands when the turn finishes. You do not have to wait for a turn to finish. The composer stays open while the agent works: anything you send waits in a **Queued messages** tray above the composer and is handed to the running agent at its next opportunity. **Claude Code** picks those up mid-turn, at the agent's next tool boundary, so a correction like "use pnpm, not npm" lands while the work is still going. **Cursor**, **OpenCode**, **Codex**, **Pi**, **OpenClaw**, and other one-shot runtimes drain the queue at turn boundaries instead. The message enters the thread itself only when the agent picks it up, in the exact spot where it took effect; until then you can remove it (the × on its row). Pressing **Stop** ends the current turn; messages still waiting are sent automatically a few seconds later as the next turn, with the agent's context intact. Each chat thread is backed by one persistent sandbox session. Follow-up messages reuse the same session and the same files, and the agent resumes its earlier reasoning rather than starting cold. Because the session belongs to the thread, the thread also keeps its agent: the chat picker pins to it, and switching agents elsewhere never re-routes this thread — start a new chat to use a different one. Deleting or archiving the thread tears the sandbox down and frees its resources. ## What the sandbox can reach The sandbox starts from an empty working directory and is locked down by default. Files and folders you pin with `@` in your message ride along into the sandbox at `/user/uploads/`, so the agent can open the actual bytes rather than work from a retrieval snippet. Outbound network is denied except for a small allowlist (package registries and GitHub), so the agent can install dependencies and clone public repositories but cannot reach arbitrary hosts. By default the model is reached through the workspace's gateway, never a raw provider key — the sandbox only ever holds a short-lived, budget-scoped key for that turn. That default is the agent's _managed_ credential mode; the _bring-your-own_ alternative, covered below, deliberately puts your own provider key inside the box instead. Beyond that lockdown, the agent can reach any integration your org has connected — search the web through Tavily, call an API, query a database — as long as that integration is bound to the agent. You bind them the same way as for any other agent: open the agent's **Tools** tab and pick them under **Bound integrations**. The credential never enters the sandbox; when the agent calls an integration, the request is brokered back to Tale, which runs the call with the stored credential and hands back only the result, so a compromised container cannot read your keys. A write operation does not run silently — it surfaces as an approval card in the chat and proceeds once you approve it. The workspace's own data rides the same brokered path. On that same **Tools** tab you can also grant **platform tools** — knowledge search, browsing and reading documents, and saving files to the documents hub — and the agent calls them from inside the sandbox as it works. Each call executes on the platform under the agent's own knowledge scope and hands back only the result, so the sandbox never holds a platform credential either, and saving to the hub surfaces the same approval card as any other write. Tools you leave unbound cannot be called, and a bring-your-own agent, which runs without a session key, has no tool bridge at all. GitHub is the exception that also places a token inside the sandbox, because `git` and the `gh` CLI need it locally: connect GitHub under [Integrations](/platform/integrations/overview) and bind it to the agent, and the session receives a scoped token so the agent can clone, push, and open pull requests on your behalf. Every credential — the in-sandbox GitHub token and the brokered ones alike — is scoped to the session, audited on each call, and revoked when the session ends. ## Managed and bring-your-own credentials How the agent reaches its model is a per-agent choice, set on the agent's **Instructions** tab under **Credentials**. Three credential backends exist; the UI labels them from the agent's runtime. **Gateway-managed (Claude Code, OpenCode, Hermes Agent, Gemini CLI, Codex, Pi, and OpenClaw, managed)** is the default for those runtimes. The platform mints a short-lived virtual key for the turn, routes the agent through its gateway, enforces the agent's allowed models from the **Providers** catalogue, meters usage, and applies the org's spend caps. The sandbox never holds a real provider key. Hermes and Codex managed runs use an OpenAI-compatible gateway route (`OPENAI_BASE_URL` + session virtual key inside the sandbox; Codex speaks the OpenAI Responses API to it); Gemini CLI managed runs use the gateway's Google GenAI-compatible route (`GOOGLE_GEMINI_BASE_URL` + the session virtual key as `GEMINI_API_KEY`); Pi managed runs use the OpenAI-compatible route too, wired as a per-turn Pi provider config that references the session virtual key from the environment (the config file never contains the key); OpenClaw managed runs use the gateway's OpenAI-compatible route through a generated per-turn provider config. **Env-managed (Cursor, managed)** applies to runtimes that authenticate with an API key you store on the agent, not through the gateway. Open the agent's **Environment** page and set `CURSOR_API_KEY` (or the key the runtime declares). The model is a **runtime id** you type on the Instructions **Models** list — `composer-2.5`, for example — not a catalogue entry. These turns are **not** metered into Usage analytics; billing lives on your Cursor account. **Bring your own (BYO)** takes the platform out of the request path for supported runtimes (Claude Code, Cursor, Gemini CLI, Codex, Pi, and OpenClaw today). No virtual key is minted; the agent authenticates with credentials you store under [Environment variables & secrets](/platform/member/environment) and reaches the provider directly. The model becomes a raw runtime id you type verbatim rather than a catalogue entry. Because the gateway is bypassed, the org's model allowlist, spend caps, and usage metering do not apply to BYO turns — billing and limits move to your own provider account. Switching an agent from managed to BYO clears its saved platform models when they were catalogue references; you re-enter raw ids. **OpenCode is managed-only** — its runtime config points at the platform gateway and authenticates with the session virtual key, so BYO is not available for OpenCode agents. Configure models from the **Providers** catalogue the same way as gateway-managed Claude Code. That is also a shift in the trust boundary. In gateway-managed mode the sandbox holds only a budget-scoped gateway key; in env-managed or BYO mode your real credential is injected into the sandbox environment — the same posture as the in-sandbox GitHub token — so any code the agent runs in the box can read it. That is by design: it is your box and your credential. Configuring an agent is already a privileged action, so the per-agent toggle is the only control; there is no separate org-level switch. ## Engines and models **Claude Code**, **Cursor**, **OpenCode**, **Hermes Agent**, **Gemini CLI**, **Codex**, **Pi**, and **OpenClaw** are separate entries in the chat picker (or agents you configure with `agentKind` set accordingly). For **gateway-managed Claude Code, OpenCode, Hermes Agent, Gemini CLI, Codex, Pi, or OpenClaw**, the model comes from the agent's supported-models list in the **Providers** catalogue — pick it in the model selector. The shipped Claude Code and OpenCode defaults include Claude Fable 5, and Fable capacity is rationed: a request its safety classifiers flag, an overloaded model, or exhausted Fable usage does not fail the turn — the session falls back automatically to the catalogue entry's fallback model, Claude Opus 4.8 (Claude Code only; OpenCode uses the gateway model id you select). Hermes Agent, Pi, and OpenClaw ship with Claude Sonnet 4.6 and Claude Opus 4.8, Gemini CLI ships with Gemini 3 Pro and Gemini 3 Flash, and Codex ships with GPT-5.5 and GPT-5.5 Pro; all of them run the whole turn on the model you picked — they have no automatic fallback. One OpenClaw caveat: its runtime reports headlessly at the end of the turn, so the chat shows the final reply and usage rather than a live tool-by-tool timeline. For **env-managed Cursor** (and BYO on any runtime), the Instructions **Models** editor accepts **runtime ids** from your account — run `agent models` inside a sandbox session to see what your subscription exposes. Leave the list empty to let the runtime pick its default (Auto). The chat model picker shows a read-only indicator — the configured id's short name, or **Default model** when the list is empty — rather than the catalogue dropdown. A **BYO Hermes Agent** uses credentials you store under [Environment variables & secrets](/platform/member/environment) — commonly `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, or `ANTHROPIC_API_KEY` depending on your provider. Set the model to a Hermes/OpenRouter-style id (for example `openrouter:anthropic/claude-sonnet-4.6`). A **BYO Gemini CLI** agent uses your own Google credentials from [Environment variables & secrets](/platform/member/environment) — `GEMINI_API_KEY` for the Gemini API, or `GOOGLE_API_KEY` with `GOOGLE_GENAI_USE_VERTEXAI=true` for Vertex AI. Type raw Google model ids (for example `gemini-3.1-pro-preview`); the shipped catalogue-shaped defaults are translated to their Google-native ids at runtime. A **BYO Pi** agent uses credentials you store under [Environment variables & secrets](/platform/member/environment) — commonly `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, or `OPENAI_API_KEY` depending on your provider. Set the model to an id from Pi's own catalogue (run `pi --list-models` in a sandbox session) — for example `anthropic/claude-sonnet-4.6` with an OpenRouter key; the shipped catalogue-shaped defaults are translated to those OpenRouter-style ids at runtime. Pi has no built-in web tools, so outside facts come through the integrations it is bound to or whatever `curl` can reach on the sandbox allowlist. A **BYO OpenClaw** agent uses credentials you store under [Environment variables & secrets](/platform/member/environment) — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY` depending on your provider. Set the model to an OpenClaw `provider/model` ref (for example `anthropic/claude-sonnet-4-6`), or leave it empty for the runtime default. A **BYO Codex** agent uses the `OPENAI_API_KEY` you store under [Environment variables & secrets](/platform/member/environment) and talks to OpenAI's own API. Shipped catalogue references translate to the entry's `nativeModelId` (`gpt-5.5`, say); ids you type yourself pass through unchanged. A **BYO Claude Code** agent types raw Anthropic ids — `claude-opus-4-20250514`, say — in priority order. Shipped pack agents that still carry catalogue-shaped refs are translated at runtime via each catalogue entry's `nativeModelId`; ids you typed yourself pass through unchanged. ## Cost and budget External-agent turns can be long and call the model many times, so they cost more than a single chat reply. Each managed turn runs against a per-turn budget, and the org's [Policies and limits](/platform/admin/governance/policies-and-limits) cap spend per user, per team, or per agent. Usage is metered into [Usage analytics](/platform/admin/governance/usage-analytics) alongside every other agent, attributed to the external agent so you can see what these runs cost. This accounting is a property of the **gateway-managed** path, so it covers Claude Code, OpenCode, Hermes Agent, Gemini CLI, Codex, Pi, and OpenClaw managed turns. Env-managed and bring-your-own agents run on credentials outside the gateway: their turns are not metered into Usage analytics and the org's spend caps do not apply, and the cost and any rate limits live with your provider account instead. ## Coding agents on the task board In settings, **Coding agent** is the product label for agents whose chat runs in a sandbox CLI (Claude Code or Cursor), or whose task dispatch is configured in JSON with a **`runtime`** (tale-daemon on your machine) or **`preferDurableStepForTasks`** (durable sandbox step). That label does not by itself change how board tasks run — dispatch follows those JSON fields, not the chat sandbox. When you assign a coding agent to a board task, what happens depends on its configuration: - **Agent** (platform tool loop, no sandbox CLI, no task runtime) — uses platform tools and posts results as task comments. - **Coding agent + `runtime`** — tasks run on your machine (tale-daemon) in a git workspace. - **Coding agent + `preferDurableStepForTasks`** — tasks run in a sandbox container; the result is a summary file. - **Coding agent, sandbox only** (external-agent chat, no runtime or durable flag) — chat runs in a sandbox; **board tasks use the platform loop** unless you bind a daemon or enable durable tasks in the agent JSON. The assignee picker surfaces these hints when you pick an agent. For research, writing, or personal deliverables, assign a person or a platform **Agent** rather than a coding agent tuned for repository work. ## Where this fits An external agent turns a chat thread into a live session with a coding tool in a sandbox — you drive it in plain language, it works in an isolated workspace, and the session persists for follow-ups until you close the thread. Credentials are the axis that decides how much of that runs under the org's control: a managed agent stays on the platform gateway under the org's caps and metering, while a bring-your-own agent runs on the keys you keep under [Environment variables & secrets](/platform/member/environment) and answers to your own provider account. The drift candidates here are the agent and model names; pair this page with the running [Providers](/platform/admin/providers) list rather than memorising specific model strings, and with [Integrations](/platform/integrations/overview) for the connected integrations the agent can reach — from GitHub for a real pull-request workflow to a search or data integration that pulls outside facts into the work. To run Claude Code or Codex on hardware you control instead of the managed sandbox — for board tasks rather than chat — see [tale-daemon](/self-hosted/operate/tale-daemon). # Image generation Source: https://tale.dev/docs/platform/agents/image-generation Any assistant in Tale can generate images. Ask it to create, draw, or design something and it produces the image inline, the way an attachment renders in the reply — there's no separate mode to switch into first. This works whenever the workspace has an image-generation model configured; this page covers the wiring. The mechanics depend on the underlying provider — quality, cost, and speed vary widely. Tale's job is to expose the capability to the agent and the user; the provider's job is to make the image. ## Asking any assistant for an image Every assistant carries an image tool it reaches for when you ask it to create a picture, logo, or illustration. The assistant calls the tool, the image renders inline, and its text wraps around the result the way it would around an uploaded attachment. Because the tool ships with every assistant, the **Auto** assistant handles an image request too — you don't have to pick a specialised agent first. The image comes from the workspace's image-generation model — the one an admin set up under [Providers](/platform/admin/providers) and tagged **Image generation**. There's nothing to configure per agent. When the workspace has no such model, the assistant tells you image generation is unavailable instead of guessing, so an admin knows to add one. ## The dedicated image surfaces Two heavier shapes exist beyond the inline tool. On the agent editor, the tool itself is **Generate image** under the Tools tab's **Images** category — untick it for an agent that should never produce pictures. And an agent's type (on the **General** tab) can be set to **Image generation**, which routes every message straight to an image model — the shape behind the catalog's **Image Creator** agent, which generates and edits images from text prompts. Reach for the dedicated type when the agent's whole job is imagery; leave the inline tool for everyone else. ## How it surfaces When the agent generates an image, the reply renders it inline next to the agent's text. Hovering shows a small **Image preview** chip; clicking opens the full-size preview with **Previous image** and **Next image** controls if the reply produced more than one. The image is stored in the chat's object store alongside attachments and inherits the chat's retention rules. ## Cost and budget Image models cost more per call than text models — sometimes ten times more. The org's [Policies and limits](/platform/admin/governance/policies-and-limits) can cap image cost per user, per team, or per agent; hitting the cap surfaces as a toast and the image fails to render. Cost is visible in [Usage analytics](/platform/admin/governance/usage-analytics) under the same Top Models table as the text models. ## Where this fits Image generation rides on one thing — a model tagged **Image generation** in the workspace — and from there every assistant can produce a picture inline, the **Auto** assistant included. The drift candidate here is provider and model names; pair this page with the running models list in [Providers](/platform/admin/providers) rather than memorising specific model strings. # Agent knowledge Source: https://tale.dev/docs/platform/agents/knowledge Knowledge is what an agent can retrieve and cite at reply time. Without it the agent is generic; with it the agent answers from your documents and cites where the answer came from. The agent's **Knowledge** tab controls two things: _how_ the agent retrieves (the retrieval mode) and _what_ is in scope (which documents). ![The agent editor's Knowledge tab with Tool picked among the four retrieval modes, the team and organization document toggles both on, a team-documents box reading that no documents were found for this team, and the organization documents list where every file carries an Indexed badge.](/images/platform/agent-editor-knowledge.webp) ## Pick a retrieval mode Four modes trade cost against coverage. **Tool** lets the agent search on demand — retrieval runs only when the model decides it needs it. **Context** injects relevant knowledge into every response, whether the model would have asked or not. **Both** combines them, and **Off** disables the knowledge base for this agent entirely. Start with **Tool**; move to **Context** when the agent's whole job is answering from the documents and you want retrieval on every reply. ## Scope the documents The knowledge base searches documents uploaded to your organization — the same library you manage under [Documents](/platform/knowledge/documents). Two switches set the scope: **Include team documents** covers the agent's assigned team, and **Include organization documents** covers documents not assigned to any team. The tab lists what each scope currently contains, with the index state per document — only **Indexed** documents are retrievable. ## Give the agent its own documents **Agent documents** are uploads only this agent can access — click **Upload documents** and the files join this agent's retrieval scope without entering the shared library. Reach for them when the source belongs to the agent's job rather than the org: a triage playbook, a product-specific FAQ. ## How retrieval lands in the reply When the agent retrieves, citations attach to the sentences they support — hovering shows the source, clicking opens it. Everything retrievable competes for relevance on every question, so keep the scope tight: a broad scope makes retrieval noisier, not smarter. ## When to reach for it Structured records and live sources are tools, not knowledge — and files for a single conversation are attachments. The boundaries: | Use… | When the agent needs… | | --------------------------------------------------- | ------------------------------------------------------- | | Knowledge (this tab) | To search and cite uploaded documents on every chat | | [Tools](/platform/agents/tools) | Customers, products, vendors, websites, or live systems | | [Attachments](/platform/chat/attachments) | A file that matters for one chat only | | [Project agents](/platform/projects/project-agents) | Knowledge scoped to one Project | ## Where this fits Agent knowledge is the answer to "this agent should answer from these documents". The wider [Knowledge](/platform/knowledge/overview) section is where the sources live and get indexed; this tab wires one agent into a scope of them. For the end-to-end build — upload, scope, ask, verify the citations — walk [Agent with knowledge](/tutorials/editor/agent-with-knowledge). # Agent skills Source: https://tale.dev/docs/platform/agents/skills A skill is the unit Tale reaches for when the same pattern appears across multiple agents. It is a reusable bundle — a `SKILL.md` with instructions, plus optional scripts, references, and assets — that lives in the org's skill library and that agents read at runtime. Bind the same skill to three agents and you maintain the behaviour in one place. This page hands you the mental model for when a skill is the right move and when inline instructions are. Read it before you upload your first skill; come back when an agent's instructions are getting long and you are wondering whether to split them out. ## What a skill bundles A skill is uploaded as a zip with `SKILL.md` at the root. The file's frontmatter carries the metadata — description, license, recommended Python or Node versions — and the body carries the instructions. Bundle assets live under `scripts/`, `references/`, or `assets/`: code the agent can run when it works in a sandbox, and reference material it can read on demand. A pure-instruction skill is the right shape when the behaviour is voice or constraint — "always cite the source by section number", "refuse questions outside this product". A skill with scripts is the right shape when the behaviour is a calculation, a transformation, or a multi-step task the model would otherwise have to improvise in tokens. ## Binding to an agent A skill becomes visible to an agent by binding it on the agent's **Skills** tab — **Bound skills** lists the org's library with a checkbox per skill. An agent can bind at most ten skills, and an agent with none bound sees none: there is no implicit fallback to org-wide visibility. The agent reads a bound skill at runtime — the description tells it when the skill applies, and it pulls in the body and bundle files when they do. The binding is per agent: two agents can bind the same skill, and unbinding is symmetric — the next request runs without it. For **external agents** (Claude Code, Cursor, and other sandbox runtimes), workflow disciplines such as fix-bug and write-notes load automatically each turn — you do not bind them on the Skills tab. Use the tab to bind **extra org skills** only; bound skills are staged into the session as files the runtime discovers natively. ## Managing the library Managing skills takes Admin or Developer permissions. The library lives in the org's Skills settings, where each skill shows its overview, instructions body, bundle file tree, and a **Recent changes** audit trail. **Upload skill** adds a new bundle, **Replace bundle** overwrites an existing one in place, and **Duplicate** forks it under a new slug. There is no version pinning: replacing a bundle changes what every bound agent reads from the next request, and deleting a skill removes the bundle from disk — any agent currently bound to it loses access. ## When to reach for it | Use … when | Skill | Inline instructions | | -------------------------------------------------------------- | ----- | ------------------- | | The pattern repeats across multiple agents | ✓ | | | The behaviour involves scripts the model would otherwise mimic | ✓ | | | The behaviour is one agent's voice | | ✓ | | You want the org to govern the behaviour through a single edit | ✓ | | | The agent's instructions still fit on one screen | | ✓ | Inline instructions are the right shape for one agent. Skills are the right shape when the same behaviour shows up in two or three agents and the maintenance cost of keeping their inline instructions in sync starts to bite. ## Build one Skills are the level of abstraction above the four knobs — they let you ship a behaviour once and have every agent that needs it pick it up by binding. The natural next walk is [Build a custom tool](/tutorials/developer/build-a-custom-tool) — it goes from a blank page to a skill with scripts bound to an agent. # Agent tools Source: https://tale.dev/docs/platform/agents/tools Tools are what an agent can do beyond producing text. The model decides which tool to call from the list the agent's author has granted; Tale runs the tool, hands the result back, and the model continues. The agent's **Tools** tab is that list — a searchable catalog of per-tool switches, grouped into category cards. ![The agent editor's Tools tab scrolled to the category cards, with Knowledge at three of four tools checked and Files at seven of seven, while Conversations, Discussions, Analytics, and Tasks & projects have none granted.](/images/platform/agent-editor-tools.webp) ## Granting tools one by one Check a tool and the agent can call it from the next request; uncheck it and the agent forgets it exists. **Search tools…** filters the catalog by name or category, each tool row carries a one-line description of what it grants, and a category's header checkbox enables the whole group at once — the count beside it shows how many of the group's tools are on. The categories map to the platform's surfaces: **Customers**, **Products**, **Vendors**, and **Websites** expose read and update tools over structured records; **Conversations** and **Discussions** let the agent read and reply; **Knowledge** covers document search and writing; **Tasks & projects** includes the agent's own to-do list; **Workflows** lets it create and run workflows; **Files** covers the agent's file operations; **System** holds **Run code**, **Ask a human**, and the other runtime tools. Grant the smallest set that does the job — every enabled tool widens what the agent can read or change on your behalf. **Run code**, in the **System** group, is the widest of these: it runs Python, Node, or bash in the chat's own sandbox, over the files the chat already holds rather than a blank box. A call runs a snippet directly, runs a script the agent staged under `/user/code/`, or installs packages only — declared packages install first and persist for the rest of the turn, and whatever the run writes under `/user/output/` comes back as a file in the chat. Files and folders you pin with `@` arrive in that sandbox under `/user/uploads/`, so the code opens the real bytes, not a retrieval snippet. An agent spawns a focused **worker** for a sub-task on its own — it is not a tool you toggle here. See [Agent workers](/platform/agents/delegation) for when that is the right move and how a worker inherits a bounded subset of the agent's own capabilities. ## Configuring web search **Web search** at the top of the tab is a mode, not a checkbox: **Off**, **Tool** (the agent searches on demand), **Context** (relevant web results are injected into every response), or **Both**. Web search only searches content from websites added to your organization — it is not an open crawl; manage the sources under [Websites](/platform/knowledge/crawling). ## Binding integrations and workflows Below the catalog, **Bound integrations** and **Bound workflows** attach specific integrations or workflows as dedicated tools, so the agent can call them without naming the integration or the workflow id itself. Bind the ones the agent's job depends on; connected [MCP servers](/platform/integrations/mcp-servers) reach the agent the same way, through the org's integrations. ## How tool calls render Tool calls appear in the chat as collapsed cards between the user's message and the reply. Expanding a card reveals the tool name, the inputs the model emitted, and the result Tale returned. A failed tool call shows the error; the model usually retries with a different shape on the next turn. ## When to reach for it | Use Tools when… | Use Knowledge when… | | ---------------------------------------------- | ------------------------------------------ | | The agent must act — query, update, run, reply | The agent must cite documents it retrieved | | The data is structured records or live systems | The data is uploaded or crawled content | ## Where this fits Tools widen what an agent can do; they also widen the trust boundary, since the agent can now read, write, or call things on the user's behalf. Pair this page with [Run-code policy](/platform/admin/governance/run-code-policy) if the agent will execute code. The agent's instructions stay the place where the **policy** lives; the **Tools** tab is the place where the **surface** lives. # Agent versions Source: https://tale.dev/docs/platform/agents/versions Every save of an agent creates a snapshot. The **History** button at the top right of the agent editor opens those snapshots in reverse chronological order; comparing shows what changed, and restoring replaces the current state with a past version. There is no manual-save versus auto-save distinction — every persisted change is a version. The mechanic is small but load-bearing. Most teams adjust an agent's instructions weekly; without the history, the team would never trust the edits. ## Reviewing a change Open the agent and click **History**. The list shows **Current version** at the top and every prior **Snapshot version** below, with the author and timestamp on each row. Pick a snapshot and **Compare changes** reviews the differences between it and the current version — the changed fields highlight — before you decide to restore. ## Restoring a version From a snapshot, click **Restore this version**. The agent's current state is replaced with the snapshot — a toast confirms **Agent restored from history** — and the restore lands on the timeline as its own entry, so restores are additive, not destructive. Chats already running against the previous version continue on it until they end; the restored version applies from the next chat. ## What gets versioned Versioning covers the agent's configuration: instructions, the model list, tool selections, knowledge settings, conversation starters, and metadata. It does not cover the underlying knowledge sources — replacing a document the agent retrieves from changes what the agent answers without bumping the agent's version. To audit a knowledge change, see [Audit logs](/platform/admin/governance/audit-logs). ## Where this fits Versions are the agent's safety net for the same reason git is the codebase's: anything saved is recoverable. The companion page is [Audit logs](/platform/admin/governance/audit-logs) — it covers the org-wide who-did-what trail; History covers the per-agent what-was-it trail. # Agent webhooks Source: https://tale.dev/docs/platform/agents/webhook-triggers An agent's **Webhooks** tab creates unique URLs external systems can POST to and chat with the agent — nothing in the UI is involved. Reach for it when something outside Tale needs the agent to answer: a Slack bot, a form handler, a scheduled job. This page covers the per-agent webhook surface only. For inbound triggers that run a workflow rather than an agent, see [Workflows → triggers](/platform/automations/triggers); for the full developer surface, see [Develop → API reference](/develop/api-reference). ![The agent editor's Webhooks tab showing the Create webhook button and a table with one webhook URL, an active toggle, and a Never last-triggered value.](/images/platform/agent-editor-webhooks.webp) ## Create a webhook Open the agent, switch to **Webhooks**, and click **Create webhook**. The dialog shows the new URL once — save it, because the token embedded in the URL acts as the authentication credential. There is no separate API key or header: anyone holding the URL can chat with the agent, so treat it like a secret. ## Call it POST a JSON body with a `message` field; the response is the agent's reply: ```bash curl -X POST https://tale.yourcompany.com/api/agents/wh/ \ -H "Content-Type: application/json" \ -d '{"message": "Hello"}' ``` Three fields shape the call: - **`stream`** — add `"stream": true` and the reply arrives as server-sent events instead of one JSON response. - **`threadId`** — without it, every POST starts a fresh conversation; pass the thread id from a previous response to continue one with context intact. - **Files** — send `multipart/form-data` with a `message` field and one or more `file` fields to attach uploads to the message. Each row's **Usage examples** action opens ready-made samples for all of these, filled in with the row's real URL. ## The OpenAI-compatible endpoint Appending `/chat/completions` to the webhook URL exposes an OpenAI-style ChatCompletion endpoint, so off-the-shelf OpenAI clients can point at an agent: use the webhook URL as the base URL, any non-empty value as the API key, and a model id from the agent's model list (unrecognised values fall back to the default). File uploads are only supported on the base webhook URL, not on this sub-path. ## Manage and revoke The table shows each webhook's URL, an **Active** toggle, and when it was last triggered. Toggling a webhook off pauses it without losing the URL; deleting it is the revocation move — any system still using that URL loses access, so provision the replacement webhook before retiring the old one. ## Where this fits Webhooks are the lightweight, per-agent integration surface — right when the integration is "this one agent answers this one thing". For richer flows with steps and approvals, model the work as an [automation](/platform/automations/concepts) and point the caller at the automation's webhook trigger — [Trigger automation via webhook](/tutorials/developer/trigger-automation-via-webhook) walks that shape end to end. # Approval concepts Source: https://tale.dev/docs/platform/approvals/concepts An approval is the seam between an agent's initiative and your judgement: a card that appears in the chat where the action was attempted, holding that action until a person decides. Agents propose — a document write, an outbound API call, a workflow run — and nothing executes while the card is pending. The chat composer says so explicitly: **Respond to the pending request above to continue**. This page is the mental model — what fires an approval, what the card offers, and what a decision leaves behind. The workflow-specific gates live on [Approvals in workflows](/platform/automations/approvals-in-workflows); where the requirements are declared lives on [Configure approvals](/platform/approvals/configure). ## What fires an approval Every card comes from an agent trying to act on something that outlives the conversation: - **Plans** — an agent proposes a multi-step plan as a **Proposed plan** card; **Approve & execute** starts it. - **Document writes** — a **Save to documents** card holds files an agent wants to store; nothing lands in the document hub until approved. - **Knowledge writes** — a **Save to knowledge base** card holds a fact an agent wants to remember org-wide. - **Integration calls** — an operation flagged as requiring approval (outbound writes, typically) holds with the exact parameters shown. - **MCP tools** — a tool the server marks **Requires approval** asks before it runs. - **Workflow creation, updates, and runs** — the workflow-side gates, covered in [Approvals in workflows](/platform/automations/approvals-in-workflows). ## The decisions on a card Every card carries the action's exact payload — the file, the fact, the parameters — and two decisions: approve (the button names the action, such as **Run workflow** or **Approve & execute**) or reject. Integration cards add a third path, **Suggest changes**: describe what is wrong in free text and the agent revises the call instead of abandoning it. Approvals are decided in the conversation they interrupt — by whoever holds that chat. There is no separate approval inbox or routing to an approver pool; the person the agent works for is the person who decides. ## States and the trail A card moves through **Pending** to **Executing** to **Completed** — or **Rejected** — and keeps its resolved state in the transcript, so a chat rereads as a record of what was allowed. Each decision also lands in the [audit log](/platform/admin/governance/audit-logs) with the actor, the action, and the timestamp. Resolved cards cannot be re-opened; a retry means a fresh proposal and a fresh card. ## Where this fits Approvals are what let you hand agents real capabilities — files, APIs, workflows — without handing over the record of who allowed what. Read [Configure approvals](/platform/approvals/configure) next to see where a requirement is switched on, and [Approvals in workflows](/platform/automations/approvals-in-workflows) for the gates around workflows. # Configure approvals Source: https://tale.dev/docs/platform/approvals/configure Approval requirements in Tale are declarative: each capability carries its own flag saying whether an agent must ask first, and the flag travels with the integration or server that provides the capability. There is no central rules table to maintain — this page shows where each flag lives and how to read what will ask before it runs. The model of what an approval card is and who decides it lives on [Approval concepts](/platform/approvals/concepts). What follows is the configuration surface, capability by capability. ## Integration operations Every integration declares its operations, and each operation carries its own approval flag. Open **Settings > Integrations**, click an integration, and its operations list badges the ones marked **Requires approval** — for the shipped connectors, that is the write side: sending mail, posting messages, creating issues. Reads run without a card; flagged writes hold in chat with their exact parameters until someone approves. For a custom integration, the flag is `requiresApproval` per operation in the `config.json` you package with **Add integration** — decide at authoring time which of its operations are consequential enough to ask. ![The Settings Integrations page on the All integrations tab showing a card grid of twelve connectable services such as GitHub, Slack, and Gmail.](/images/platform/integrations-catalog.webp) ## MCP tools An MCP server's manifest marks which of its tools need sign-off. Open **Settings > API > MCP**, expand a server, and its **Discovered Tools** list badges each flagged tool with **Requires approval** — those ask in chat every time an agent calls them. The flag comes from the server's author; connecting a server is how you accept its tool contract, so review the list before activating one. [MCP servers](/platform/integrations/mcp-servers) covers registration. ## Built-in write gates Some gates ship on and are not configurable, because the action is consequential by nature: - **Document writes** — an agent saving files to the document hub always asks (**Save to documents**). - **Knowledge writes** — an agent storing an org-wide fact always asks (**Save to knowledge base**). - **Workflow creation, updates, and runs** — an agent building, editing, or starting a workflow always asks; see [Approvals in workflows](/platform/automations/approvals-in-workflows). The lever for these is not the approval flag but the capability itself: an agent without the document tools or workflow tools never produces the card. Trim the agent's [tool set](/platform/agents/tools) to remove the capability entirely. ## Verifying what will ask Before putting an agent in front of real systems, read its capabilities the way an approver would: the integration's operations list for flagged writes, the MCP server's **Discovered Tools** for flagged tools, and the agent's tool tab for whether it holds write tools at all. The [audit log](/platform/admin/governance/audit-logs) then records every decision the setup produces. ## Where this fits Configuration here is distribution — flags live with the integrations and servers that own the capabilities. Read [Approval concepts](/platform/approvals/concepts) for the card lifecycle those flags produce, and [Agent tools](/platform/agents/tools) for the capability side of the same boundary. # Approvals in workflows Source: https://tale.dev/docs/platform/automations/approvals-in-workflows Workflows run without you, but they change and start only with you. Three human gates surround every workflow: the AI editor's changes to a definition apply only after you approve them, an agent that wants to run a workflow needs your sign-off first, and a run that hits a question pauses until someone answers. This page covers the three gates; the org-wide story of what an approval card is lives on [Approval concepts](/platform/approvals/concepts). ![The workflow editor with a step graph on the canvas and the AI editor panel open on the right, where proposed workflow changes appear for approval.](/images/platform/automation-editor-canvas.webp) ## Approving changes to a definition Ask the **AI editor** to build or rework a workflow and its proposal lands as a card in the panel — a **Create workflow** card with the step count for a new definition, or an update card badged by scope: **Update step** for a single-step patch, **Update {count} steps** for several, **Update workflow** for a full save. Approve and the change is applied and versioned like any manual save; **Cancel** discards it. Nothing touches the definition while the card is pending. ## Approving a run An agent in chat with the workflow tools can ask to start a workflow. The request arrives as a card naming the workflow — expand **Show parameters** to inspect the exact input it will run with — and holds until you click **Run workflow** or **Cancel**. After approval the same card tracks the live run: the current step, elapsed time, and the outcome, with **Stop** to cancel mid-flight and **View execution details** to jump to the run's journal. The chat composer is blocked while a request is pending — **Respond to the pending request above to continue**. Decide the card before sending the next message. ## Answering a paused run A run that needs a human answer pauses with the **Waiting for input** status in the [execution list](/platform/automations/execution-logs). The question arrives as a form card — fill it and click **Submit response**, or click **Reply differently** to push back in free text. The run resumes with your answer as the step's input, and the journal records who answered and what. ## What each decision leaves behind Every gate resolves to the same states — **Pending**, **Executing**, **Completed**, or **Rejected** — visible on the card itself, and the decision lands in the [audit log](/platform/admin/governance/audit-logs) with the actor and timestamp. A resolved card cannot be re-opened; to retry a rejected run, ask again and decide the fresh card. ## Where this fits These gates are the workflow-side face of one product-wide pattern: an agent proposes, a human disposes. [Approval concepts](/platform/approvals/concepts) names every card type beyond workflows — document writes, knowledge writes, integration calls — and [Configure approvals](/platform/approvals/configure) shows where the requirements are declared. # Automation assistant Source: https://tale.dev/docs/platform/automations/assistant The **Automation assistant** is the chat agent pinned to whichever automation you opened — click **Assistant** on an automation's page and it answers with that automation's agents, workflow, skills, integrations, and configuration already in context. Admins and Developers use it to understand an unfamiliar automation, extend one instead of duplicating it, or get help authoring the pieces the automation page doesn't edit directly. It's the same assistant agent [the workflow editor](/platform/automations/editor) embeds, so a conversation started from one surface reads familiar from the other. ## What it edits directly Workflows are the one piece the assistant has full tool access to: it reads the current definition, edits steps, saves a new version, and runs it, the same as if you'd clicked through the editor yourself. Agents are one step behind — it reads the roster and can install, enable, or disable one, but instructions, model, and the rest of an agent's configuration stay yours to edit in the agent editor; the assistant drafts the exact JSON and you paste it in. ## What it drafts instead Skills, integrations, builtin views, and automation configuration have no editing tool at all: the assistant writes the definition per the matching write-skill or write-integration authoring skill and tells you exactly where to apply it — Settings > Integrations for a credential, the automation's own page for a view or its configuration. Install and setup work the same way: it walks the readiness checklist — connect what's required, fill in configuration, enable the agents and workflow — rather than doing the connecting itself. ## Finding what already exists Before building anything, the assistant searches for an automation or bundle to extend rather than duplicate — the same reuse-first rule every write-\* skill enforces. Its search reaches automations the catalog itself hides: a bundle's hidden members (see [Automation concepts](/platform/automations/concepts)) are still visible to the assistant, so it can point you at, say, the PR Creator agent buried inside Resolve GitHub issues instead of proposing a new one. ## Where this fits The Automation assistant is the fastest way into an automation you didn't build — ask it what something does before you touch it by hand. [Automation concepts](/platform/automations/concepts) is the vocabulary it assumes; [Browse and install](/platform/automations/catalog) is where you'd act on what it tells you if the automation isn't installed yet. # Built-in automations Source: https://tale.dev/docs/platform/automations/builtin Tale ships automations out of the box: three that turn a mailbox into a shared inbox, one bundle that resolves GitHub issues end to end, a set of sync and upkeep templates you install when you need them, and the pre-installed packs that run task boards and mentions for every organization. Editors and Members use whatever an installed automation adds — an Inbox tab, a Backlog entry — without installing anything themselves; installing is an Owner/Admin/Developer action covered on [Browse and install](/platform/automations/catalog). This page names what each one does and the integration it needs connected first. ![The Automations catalog on the All automations tab, showing cards for the email automations and the Resolve GitHub issues bundle, each with its icon and description.](/images/platform/automations-catalog.webp) ## Sync Gmail, Outlook, and email over IMAP **Sync Gmail emails**, **Sync Outlook emails**, and **Sync emails via SMTP/IMAP** are the same automation three times over, one per mailbox kind: each requires exactly the integration its name says, each installs the same channel-agnostic **Inbox** builtin view, and each carries the mail-sync workflow that pulls the mailbox into conversations on a schedule (every six hours out of the box — tighten it on the automation's **Triggers** tab). An organization that receives mail on more than one kind of mailbox installs more than one of these; each Inbox only shows its own mailbox's traffic. | Automation | Requires | Mailbox | | ------------------------- | --------- | -------------------------------------- | | Sync Gmail emails | Gmail | A Gmail mailbox | | Sync Outlook emails | Outlook | A Microsoft Outlook mailbox | | Sync emails via SMTP/IMAP | IMAP/SMTP | Any private mailbox over IMAP and SMTP | ## The Inbox tab Every one of the three opens on its **Inbox** tab: four sub-tabs — **Open**, **Closed**, **Spam**, **Archived** — each a split view with the conversation list on the left and the selected thread on the right. Opening a conversation fills the right pane with its full message history; until you pick one, the pane reads **Select a conversation to view details**. The composer sits under the thread on **Open** — replies belong to active conversations, so the other three tabs are read-only. Write in **Type a message** and click **Send**; the reply goes out through the mailbox the conversation arrived on, with the recipient and subject line derived from the thread — there's nothing to address by hand. **Improve** rewrites your draft with AI before you send it. On the IMAP automation, replies sent from the mailbox itself — from any mail client — sync into the conversation too, ordered with the rest of the thread. The thread header carries the status verbs for whichever conversation is selected — **Close conversation** and **Mark as spam** on an open thread, **Reopen conversation** on a closed or archived one, **Not spam** and the destructive **Delete** on spam. Selecting several rows in the list surfaces the same verbs as bulk actions. ## Resolve GitHub issues **Resolve GitHub issues** is a bundle, not a single automation: installing it runs one aggregated wizard that installs four hidden automations at once, bound to the project you choose, and requires the GitHub integration. Each member does one stage of the loop. **Triage GitHub issues** scores a repository's open issues on a schedule and proposes the actionable ones onto the project's [Backlog](/platform/projects/backlog) — titled `# `, labelled to match GitHub, and left for a human to review. **Sync GitHub issues** closes a task the moment its GitHub issue closes, whether the resolve chain merged the fix or a human closed the issue directly on GitHub — it only closes, never creates or reopens a task. **Create GitHub pull requests** ships the PR Creator agent: once a human Starts a proposed task, it clones the repository, opens or adopts the pull request for the issue, implements the fix, verifies it against the project's own tests, and waits for CI to go green. **Review GitHub pull requests** ships the PR Reviewer agent: it re-tests the PR Creator's branch, confirms CI, and a toolless judge decides mergeability — approved parks the task at **In review** for a human to merge on GitHub; not approved sends it back to the PR Creator with feedback, up to a small rework cap. A human stays in the loop at two points: starting a proposed task off the Backlog, and merging the pull request on GitHub itself — nothing in the bundle merges on your behalf. ## Sync and upkeep templates Eight more automations sit in the catalog for the moments you need them. Each is a single workflow you install and then point at your data — the sync ones ask for their source on the schedule they create, and every one is editable afterwards on the automation's **Editor** tab. | Automation | Requires | What it does | | ---------------------------------- | ------------ | ----------------------------------------------------------------------------- | | Sync Confluence pages | Confluence | Imports a Confluence space's pages into the knowledge library on a schedule | | Sync Google Drive files | Google Drive | Imports a Drive folder's documents into the knowledge library | | Sync Shopify customers | Shopify | Imports the shop's customers into the organization's customer records | | Sync Shopify products | Shopify | Imports the shop's product catalog into the organization's product records | | Analyze product relationships | — | Scans the product catalog and records accessories, variants, and complements | | Index documents for retrieval | — | Indexes newly uploaded documents so agents can search and cite them | | Archive idle conversations | — | Closes out conversations that sat quiet past their idle window | | Notify members on inbound messages | — | Alerts members the moment a new inbound message lands in an open conversation | ## The pre-installed packs The plumbing that runs every organization's boards ships as automations too — installed automatically at creation, hidden from the catalog, and visible on the **Installed** tab like anything else. The **task pack** runs an assigned agent the moment a task lands on it, triages unassigned work, reacts to @-mentions, routes finished work through review, sweeps stale runs, enforces SLAs, and keeps dependent tasks, subtasks, and archives moving; its siblings answer discussion mentions and keep OneDrive files synced. Each is a normal automation — open one to read its workflow on the **Editor** tab, watch it under **Executions**, or switch off a trigger under **Triggers**; an uninstall sticks and is never re-installed behind your back. ## Where this fits The inbox automations, the Resolve GitHub issues bundle, and the sync templates are what ships today; a private automation your organization builds or uploads shows up in the same catalog next to them. [Browse and install](/platform/automations/catalog) covers the catalog mechanics; [Project Backlog](/platform/projects/backlog) is the next read for what happens to a task after Triage proposes it. # Browse and install automations Source: https://tale.dev/docs/platform/automations/catalog The Automations catalog (**Automations** in the sidebar) is where Owners, Admins, and Developers browse every automation available to the organization and decide which ones are installed. This page covers the catalog itself — the side panel a card opens, the install wizard, and the reinstall, uninstall, and update actions that follow. What each shipped automation actually does lives on [Built-in automations](/platform/automations/builtin); the mental model for the pieces an automation bundles lives on [Automation concepts](/platform/automations/concepts). <Frame caption="The Automations catalog — every card is one installable automation; the bundle installs all its members through one wizard."> ![The Automations catalog on the All automations tab, showing cards for the three email automations and the Resolve GitHub issues bundle, each with its icon and description.](/images/platform/automations-catalog.webp) </Frame> ## Installed and All The catalog opens on **Installed** — the tab strip's default, and the only tab where a bundle dissolves into its own member cards instead of showing once as the bundle. Each member carries a small marker on its icon naming its bundle — **Part of Resolve GitHub issues**, for one — so you can still tell which ones belong together even split apart, and each keeps its own **Reinstall**/**Uninstall** in its **⋯** menu: a bundle has no install of its own to manage as one unit (see [Automation concepts](/platform/automations/concepts) for why). Switch to **All automations** to browse the whole catalog instead — built-in and uploaded, installed or not: here the bundle IS the card, installed through one wizard, and its hidden members never appear on their own. Use **Installed** to manage what's running; use **All automations** to find something new to add. ## Installing one Click a card and its side panel opens — the same click-to-preview pattern [Settings > Integrations](/platform/integrations/overview) uses for its own catalog. The panel lists what installing adds: its pages, workflows, agents, skills, and the integrations it requires, plus which project it targets if it's project-scoped. Click **Install** and the wizard opens. The wizard walks only the steps this automation actually needs: a **Project** step if it's project-scoped and you didn't open it from inside one already; a **Review changes** step if installing would overwrite files already on disk; an **Install** step that confirms what's ready and names what still needs connecting; an **Agent mode** step for every agent that can run on your own credentials instead of the platform's, followed by a connect step for each provider key or required integration that choice still leaves unconnected; and a **Done** step. The project you pick on the **Project** step does double duty: it's also where any schedule the automation installs gets its `projectId` variable seeded from, so a workflow that reads `{{input.projectId}}` fires against the right project without it being retyped on the [Triggers tab](/platform/automations/triggers). **Done** doesn't say "ready" until the automation actually is. Every required integration connected reports exactly that; a required schedule variable still blank — something no wizard step asks for, since it depends on the workflow's own input schema — is named instead, with an **Open Triggers** button that jumps straight to the schedule that needs it (a bundle's Done step does the same per member, naming which ones still need a variable set). Every setup step is finish-able later regardless: a skipped connection from the automation's own **Finish setup** checklist, a schedule variable from its [Triggers tab](/platform/automations/triggers). ## The install preflight Reinstalling or re-uploading over an automation that already changed some of its files triggers a **Review changes** step before anything is touched. For a single automation, the step lists every file the install would overwrite and asks you to confirm replacing them all with the automation's own versions in one step — there's no per-file pick-and-choose. Installing a **bundle** reviews per member automation instead: each member gets its own collapsible section and its own confirmation, so you can see exactly which of the bundle's several automations touch files you changed. Either way, a workflow's own steps are exempt from this check — see the next section. ## Reinstalling, uninstalling, and updating Every installed card carries a **⋯** menu with **Reinstall** and **Uninstall**; a not-yet-installed card's menu offers **Install** instead, plus **Delete** for a private upload you haven't installed yet. **Reinstall** re-runs the same preflight as a fresh install and keeps your environment variables and secrets. **Uninstall** removes the automation and everything it installed — its agents, workflows, pages, and their environment variables and secrets — while any integration it used stays connected for whatever else needs it. Reinstalling never touches the automation's workflow: workflow steps are update-exempt, so whatever you've edited in the editor survives every reinstall and every catalog update. To pick up a workflow's latest shipped version, uninstall the automation and install it again — Tale repeats this reminder on the reinstall confirmation and on the automation's own Configuration tab. **Update built-in automations**, in the same **Add automation** menu as **Upload package**, is a different action from either: it re-syncs every built-in automation in the organization against the shipped catalog in one pass — including ones you edited — rather than one card at a time. It carries the same workflow exemption and keeps secrets; the previous version of anything it changes lands in that automation's history. ## Uploading a private automation **Upload package** in the same menu adds an automation the catalog doesn't ship — drop a `.zip`, or select a folder containing an `automation.json` at its root; the folder or file name becomes the automation's slug. Uploading only adds it to the organization's private catalog; install it afterwards like any other card. Re-uploading over a slug that already exists asks you to confirm the replacement before it overwrites the existing package. ## Where this fits The catalog is the front door to every automation the organization can run: the side panel previews what installing adds, the wizard connects what it needs, and reinstall, uninstall, and update keep it current without touching a workflow you're mid-edit on. [Built-in automations](/platform/automations/builtin) is the next read for what each shipped automation and the Resolve GitHub issues bundle actually do; [Automation concepts](/platform/automations/concepts) is the mental model if you haven't read it yet. # Automation concepts Source: https://tale.dev/docs/platform/automations/concepts An automation is the unit Tale reaches for when a job needs more than one moving part wired together — an integration credential, one or more agents, a workflow, sometimes a page of its own — and you want all of it installed and connected in one action instead of assembled by hand. Owners, Admins, and Developers install automations from the Automations catalog; once installed, Editors and Members use whatever it shipped — an Inbox tab, a Backlog entry, a chat agent — without needing to know what's underneath. This page names the pieces an automation bundles, the workflow that makes it run, and when an automation is the right unit instead of a single agent. ## What an automation bundles An automation's manifest names up to five kinds of pieces, and most automations only use some of them. **Integrations** are the credentials its steps and agents call — Gmail, GitHub, a SQL database. An automation never stores its own copy of a credential; it names which integration it requires, and the org connects that integration once, the same connection every other automation and agent shares. **Agents** are the chat or task agents the automation installs — a triager, a PR reviewer, a summariser. Once installed they're ordinary agents: mentionable in chat, assignable on a project board, editable in the agent editor. **A workflow** is the automation's one bundled trigger-and-steps definition — the thing that actually runs on a schedule, a webhook, or a manual click. Not every automation ships one: the email automations covered on [Built-in automations](/platform/automations/builtin) have none, because reading and replying to mail is a page, not a scheduled run. **Builtin views** are pages the automation registers into the platform's shared view registry, like Inbox — the platform renders the page itself; the automation only names which one and what it's scoped to. **Configuration** is not a separate settings file. An automation that needs an operator value reads it from an integration's credential or from a workflow trigger or node variable; the automation's Configuration tab is a read-only summary of the pieces above, not a place to add new settings. ## The workflow inside There is no standalone workflow surface in Tale — a workflow lives and runs inside its automation, and the automation's **Editor** tab is where you meet it. The definition is a graph of typed steps: **LLM** steps call an agent or model, **Action** steps do concrete work such as calling an integration or creating and updating tasks on the project board, **Condition** steps branch the graph on a yes or no, **Loop** steps repeat over a set, and **Sandbox** steps run code. Every save snapshots a version you can restore from **History**. [The workflow editor](/platform/automations/editor) is the operating manual for that surface. **Triggers** decide when the workflow runs. Three kinds attach on the **Triggers** tab: **Schedules** (cron), **Webhooks** (an external POST), and **Events** (something happens inside Tale, such as `task.created`) — and you can always fire a run by hand from the editor's **Test workflow** panel. The [triggers reference](/platform/automations/triggers) covers each. **Executions** are the run history. Every run writes a record — status, timing, the input it received, and a per-step journal of what each step consumed and produced. The **Executions** tab is the audit trail and the debugging surface in one place; [Execution logs](/platform/automations/execution-logs) reads one end to end. ## Where humans fit Automations run without you, but they change and start only with you: the AI editor's proposed changes to a workflow land as approval cards before they apply, an agent that wants to run a workflow needs your approval first, and a run that needs an answer pauses as **Waiting for input**. [Approvals in workflows](/platform/automations/approvals-in-workflows) covers all three. A loop that re-enters the same review gate — a task sent back for another pass — opens a fresh request each round rather than reusing the resolved card. ## Bundles and hidden automations A bundle groups several automations that only make sense installed together. [Resolve GitHub issues](/platform/automations/builtin) installs four automations — a triager, a syncer, a PR creator, and a PR reviewer — through one aggregated wizard, bound to the project you choose. Most of a bundle's members are hidden: they never appear as their own card in the catalog, because installing one alone would be meaningless without its siblings. Hidden doesn't mean gone — the [Automation assistant](/platform/automations/assistant) can still find and explain them; only the catalog's grid hides them. ## Putting it together — two combinations **Sync Gmail emails** combines the smallest possible set: one integration (Gmail) and one builtin view (Inbox) — no agent, no workflow. Connect Gmail, and the Inbox tab is the whole automation. **Resolve GitHub issues** combines nearly every piece at once: one integration (GitHub), two agents (a PR creator and a PR reviewer, each owned by one of its four hidden members), four workflows, and no builtin view — it works through the project's existing Board and Backlog instead of a page of its own. Installing the bundle wires all four in one aggregated wizard, bound to the project you pick. ## When to reach for it | Use … when | Automation | Agent | Agent webhook | | ---------------------------------------------------------------------- | ---------- | ----- | ------------- | | You want a ready-integrated feature installed in one action | ✓ | | | | The work has multiple steps, branches, schedules, or approvals between | ✓ | | | | The same question just recurs in chat, no external system involved | | ✓ | | | One agent reply per incoming POST is enough | | | ✓ | Check the catalog before building anything — the automation you need may already ship. When nothing shipped fits, you still build an automation: describe the workflow to the [AI editor](/platform/automations/editor) or upload a package, rather than assembling loose pieces. An [agent webhook](/platform/agents/webhook-triggers) is the one seam outside this model — reach for it when a single agent reply per incoming payload is all the job needs. ## Build one An automation is the whole bundle a real feature needs — the integration it calls, the agents that do the work, the workflow that runs it, the view it renders — wired together and installed in one action, with the workflow's runtime (triggers, executions, approvals) living on the automation's own tabs. The natural next read is [Browse and install](/platform/automations/catalog) — it walks the catalog, the side panel, and the install wizard end to end; [The workflow editor](/platform/automations/editor) picks up from there for the surface where the automation's engine gets built and tuned. # The workflow editor Source: https://tale.dev/docs/platform/automations/editor This page is the operating manual for the workflow inside an automation — the surface behind the **Editor** tab. The mental model — what an automation bundles and what a definition, trigger, and execution are — lives on [Automation concepts](/platform/automations/concepts). This page is the hands-on half: where the workflow lives, how you run it from the UI, how you pause it without deleting it, how you edit and how the versioned history works. Editors and Developers read this when they are working with a workflow day to day. ## Where workflows live Workflows have no standalone tab in the sidebar. A workflow belongs to the automation it powers — open the automation and its **Editor** tab is the workflow; you manage everything below from there. A direct link to a workflow keeps working when someone shares one, so bookmarks and the links on approval cards and execution views land on the workflow itself. Every surface this page covers (the editor, the executions tab, the version history) hangs off a single workflow you opened. ## Running a workflow Three paths fire a workflow. The **Triggers** tab on the workflow attaches the production paths: **Schedules** fire on a cron, **Webhooks** accept an external POST, and **Events** subscribe to internal signals such as `task.created`. The [triggers reference](/platform/automations/triggers) covers each in depth. **Test workflow** in the editor toolbar opens the test panel and fires a one-off run. Paste the input JSON the run should receive, click **Execute**, and the run shows up in the Executions tab with its ID. Reach for the test panel when you are iterating on a workflow and want to see the full execution journal without wiring a trigger first. While the run is live, the canvas mirrors it: every step carries a status badge — a spinner while running, a check on success, an alert on failure, a pause icon while waiting for input — and a banner above the canvas names the run being viewed. Click a badge to inspect the step's duration, error, and a preview of its output. The viewed run rides the `execution` URL parameter, so it survives a reload; dismiss the banner to clear the badges. The test panel itself mirrors the same feed as a step list: each executed step appears with its live status, retried or looped steps carry an attempt counter, and a failed step shows its error message inline — click the step's name to jump straight to its settings. When a run fails before any step ran — it never started, timed out, or was canceled — the panel names that reason instead. Test runs also validate the input on the server against the start step's schema: a missing or mistyped field is rejected with a field-specific message before the run is even created. The **Debug** button on the same panel starts the run in step-by-step mode. The engine pauses before every step: the paused step carries a debug badge on the canvas, and the panel shows which step is next together with the run's variables and each completed step's output, so you can check what a step is about to receive before it runs. **Step** executes the paused step and pauses again before the next one, **Continue** runs the rest of the workflow without further pauses, **Stop** cancels the run. Debug runs appear in the Executions tab with a _Paused (debug)_ badge while paused and `debug` as their trigger source. The **Dry run** button on the same panel simulates a run without side effects — the workflow validates against the input, walks the step graph, and reports errors and warnings without calling out to any agent, API, or mail server. Reach for dry run when the workflow is not yet safe to run end to end. ## Pausing and disabling Pausing a workflow without deleting it lives on the triggers — every trigger row has an **Active** toggle. Switch each trigger off and the workflow stops firing; switch them back on to resume. The workflow itself stays in place and its history stays intact. Deleting a workflow is permanent. Tale prompts for confirmation before the delete; the executions and the version history go with the workflow. ## Editing Open the workflow and the editor surfaces the step graph on a canvas — this is the **Graph** view, one of two ways to read the same definition. Switch to **Specification** and the same workflow reads as a plain-language description you can edit directly; regenerating from either view keeps the two in sync, and a banner warns when they've drifted apart. Click a step on the graph to open its **Step editor** panel on the right; the panel carries the step's name, type, configuration, and the transitions to the next steps on success and failure. The canvas toolbar carries the zoom controls, **Test workflow**, and the **AI editor** toggle — a chat that edits the workflow for you, the same [Automation assistant](/platform/automations/assistant) embedded here. Adding steps directly on the canvas isn't wired up yet; new steps come from the AI editor or from the specification. The banner **This workflow is active — saved changes apply to new runs.** above the canvas means exactly that: edits to a triggered workflow go live on the next run. Switch its triggers off first when the edits are not ready. ## Versioning and history Every save snapshots a new version of the workflow. **History** in the workflow's navigation lists the versions newest first, each with a timestamp and the member who saved it. Opening one shows a **Compare changes** diff against the current definition; click **Restore** to roll back to that snapshot. Restoring creates a new version on top of the history — the rolled-back state is the new current, and the version you replaced still sits in the list. The history is per-workflow, not per-step. Restoring rolls the whole definition; partial restores live in the editor (copy the step config from the diff and paste it into the current version). Reinstalling or updating the automation this workflow belongs to never touches these steps — a workflow is exempt from that overwrite, precisely so your edits survive a catalog update. Uninstall the automation and install it again to pick up its latest shipped workflow instead. ## Where this fits This page is the operating manual; [Automation concepts](/platform/automations/concepts) is the mental model. The natural neighbours are [triggers](/platform/automations/triggers) (the kick-off), [execution logs](/platform/automations/execution-logs) (the per-run detail), and [approvals in workflows](/platform/automations/approvals-in-workflows) (the human gate between steps). Reach for this page when you are working with a workflow that already exists; reach for concepts when you are building your first one. # Execution logs Source: https://tale.dev/docs/platform/automations/execution-logs Execution logs are the run history of a single workflow. Every time a trigger fires, Tale opens an execution record and writes to it as the run progresses — status, timing, the input the run received, and what every step consumed and produced. The **Executions** tab is the debugging surface every other automations page points at when something went wrong. <Frame caption="The Executions tab — one row per run; the single red badge among the green ones is where a debugging session starts."> ![The Executions tab of an automation listing twelve runs — eleven with a green Completed badge and one with a red Failed badge — each with an execution ID, a start timestamp, a duration, and event as its trigger source.](/images/platform/automation-executions.webp) </Frame> ## The list view One row per run, newest first. The toolbar carries **Search by execution ID**, a **Filter**, and a date-range picker. | Column | Description | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Execution ID | Stable identifier for the run — the copy icon puts it on the clipboard. | | Status | **Pending**, **Running**, **Completed**, or **Failed** — plus **Waiting for input** when a run is blocked on a human, and **Paused** during a step-by-step debug run. | | Started at | Wall-clock start time, to the millisecond. | | Duration | Start to completion; empty while the run is still going. | | Triggered by | Which path started the run — a schedule, a webhook, an event, or a test from the editor. | ## The expanded run Expand a row and the record renders as JSON: the execution metadata (status, timing, trigger source, and the error if any), the metadata the trigger carried, the input variables, and the **journal** — one entry per executed step with its inputs, outputs, and status. A failed step carries the error string that killed it. Read the journal top to bottom and the run retells itself; the entry whose status flips is the step that misbehaved. ## Retries and re-runs Transient failures retry on their own. The workflow's **Configuration** tab sets the default — **Max retries** and **Backoff (ms)** — and any step can override it in its own config. <Frame caption="The Configuration tab — the retry budget and backoff every step inherits unless it overrides them."> ![The Configuration tab of an automation showing name and description fields, a timeout of 600000 milliseconds, max retries of 3, a backoff of 1000 milliseconds, and a variables JSON editor.](/images/platform/automation-configuration.webp) </Frame> A run that fails past its retry budget stays **Failed** for the audit trail; to try again, open **Test workflow** in the editor, paste the input copied from the failed run's variables block, and click **Execute**. The re-run is a fresh execution with its own ID. ## A worked debugging session A daily report did not arrive. Open the workflow, switch to **Executions**, and filter to today's failures — the failing run sits on top. Expand it: the journal shows the summarising step erred with a timeout, and its inputs carry the prompt it received. Fix the cause, re-run from the test panel with the same input, and watch the new execution complete before trusting tomorrow's schedule. ## Where this fits Execution logs are the receipt every workflow leaves behind. Pair them with [triggers](/platform/automations/triggers) for the kick-off that opened each record, and with [audit logs](/platform/admin/governance/audit-logs) for the org-wide trail of who changed what. # Workflow triggers Source: https://tale.dev/docs/platform/automations/triggers A trigger is what starts a workflow without a human clicking anything. The **Triggers** tab on a workflow carries three sections — **Schedules**, **Webhooks**, and **Events** — and a workflow can hold several triggers of any mix; all of them feed the same first step. A workflow with no triggers still runs by hand from the editor's **Test workflow** panel — useful while building, never for production. <Frame caption="The Triggers tab with the Events section expanded — one event trigger, its Active toggle, and its last-fired time."> ![The Triggers tab of an automation showing collapsed Schedules and Webhooks sections and an expanded Events section with a task.created trigger row.](/images/platform/automation-triggers.webp) </Frame> ## Schedules Click **Add schedule** to run the workflow on a clock. The form takes a standard 5-field cron expression, with presets from **Every 5 minutes** to **Every month** — or describe the timing in plain language and click **Generate** to let the AI write the cron for you. **Timezone** picks which zone the cron fires in, defaulting to your own browser's zone; editing an existing schedule keeps whatever zone it already runs on. **Workflow variables** are the input each scheduled run receives — and when the workflow's start step declares an input schema, the dialog renders it as a real form instead of raw JSON: a `projectId` field becomes a **Project** select defaulting to this schedule's own bound project, `owner` and `repo` together collapse into one **GitHub repository** field that takes `owner/repo` or a full GitHub URL, and every other declared field gets its own labelled input with the schema's own description as help text. A required field left blank shows its own error and blocks **Save** — the same rule the workflow editor's **Test workflow** panel already enforces, so a schedule can't be saved in a shape its own workflow would reject at run time. Click **Edit as JSON** to fall back to the raw editor for a schema the form can't represent. These variables are per-schedule, not the automation's workflow defaults shown on its **Configuration** tab — two different schedules on the same workflow can each send their own repository or project, and only what's set here reaches the run. The row shows the schedule's bound **Project** (or **No project**), its **Last triggered** time, and who created it. A schedule still missing one of its workflow's required variables carries a yellow **Needs configuration** badge — hover it for the exact field names — even while active, since a fire-time run with a blank required value fails; a schedule bound to a project already satisfies a required `projectId` without repeating it in the variables. The same gap surfaces on the automation's own **Finish setup** banner and on the [install wizard](/platform/automations/catalog)'s Done step, both linking back here to fix it. ## Webhooks Click **Add webhook** and Tale mints a unique URL; any system that POSTs JSON to it fires the run, with the request body as the run's input. <Warning> Save the webhook URL when it is shown — the token in the URL acts as the authentication credential. Anyone holding the URL can fire the workflow, so treat it like a secret and delete the webhook to revoke it. </Warning> ## Events Click **Add event trigger** and pick an event type from the dropdown — things that happen inside Tale, such as `task.created`, `conversation.message_received`, `customer.updated`, or `workflow.completed`. Optional filters narrow when the trigger fires, and the event's payload becomes the run's input. Reach for an event trigger when the workflow's job is to react to something Tale itself just did. <Note> A workflow that belongs to an [automation](/platform/automations/concepts) runs only from within its automation — it can't subscribe to events itself. </Note> ## Picking the right trigger | Use … when | Schedule | Webhook | Event | | --------------------------------------- | -------- | ------- | ----- | | The work recurs on a clock | ✓ | | | | An external system signals the work | | ✓ | | | Something Tale did is the reason to run | | | ✓ | A workflow can carry more than one — a daily schedule plus a webhook for ad-hoc external kicks is a common pair. ## Pausing and removing Every trigger row has an **Active** toggle. Switching it off stops the firing without losing the row or the run history; switching it back on resumes immediately. Deleting the row is permanent — for webhooks it also kills the URL, so any system still POSTing to it stops working. ## Where this fits Triggers are the kick-off layer; the steps after them are the actual work. Head to [Automation concepts](/platform/automations/concepts) for the model a trigger feeds into, and to [Execution logs](/platform/automations/execution-logs) to see what each fired run recorded — including which trigger started it. # Agents in chat Source: https://tale.dev/docs/platform/chat/agents-in-chat Picking an agent in Chat is the difference between asking a generic Assistant and asking something the org has shaped for a domain. The agents picker is the most-used control in the composer; the rules behind which agent appears, when an agent persists, and what happens when you switch mid-chat are the subject of this page. <Frame caption="The agent picker open over the composer — Auto, the installed agents, and the Catalog shortcut."> ![The agent picker open above the chat composer, showing a search field, an Auto entry, the selected Assistant, an Automation Assistant entry, and a Browse automations button.](/images/platform/chat-agent-picker.webp) </Frame> ## The agents picker Click the agent chip on the composer (its accessible name is **Select agent**) and the picker opens with **Search agents** at the top. The list shows **Auto** — Tale routes each message to the best-fitting agent — followed by every agent you have access to that is marked **Visible in chat**; coding agents get their own **Coding agents** section when any are visible. Agents without that toggle exist in the org but never surface here, which keeps the list short. **Browse automations** at the bottom leads to the [Automations catalog](/platform/automations/catalog) — new agents arrive as part of an automation you install. ## "Visible in chat" Every agent has a **Visible in chat** toggle on the **General** page of its editor. Turning it off does not disable the agent — automations and workflows can still call it, and sub-agent calls from other agents still work — it just hides the agent from the chat picker. The reasoning: organisations end up with dozens of agents the average user never picks (utility agents called by other agents, agents bound to a specific workflow), and surfacing them all would drown the everyday picks. ## One-shot versus sticky Picking an agent **before** the first message in a chat makes it sticky — every subsequent message in the same chat goes to the same agent. Picking an agent **mid-chat** applies it to the next message and everything after, until you switch again. <Note> There is no "use this agent once and revert" gesture — to hand the chat back, pick **Assistant** (or **Auto**) in the picker explicitly. The transcript keeps the per-message agent, so a chat with a mid-stream switch reads as two agents collaborating. </Note> ## Switching mid-thread The agent's knowledge and tools change with the picker, but the conversation history does not. The new agent reads everything that came before — your messages and the previous agent's replies — and continues from there. This is useful for handoffs: a triage agent answers the first message, you switch to a specialist for follow-up, and the specialist has the full context without anyone copy-pasting. ## Sub-agent calls An agent's instructions can include a sub-agent tool; when it does, the primary agent can delegate part of the work without you picking anything. Sub-agent calls render in the reply as collapsed tool calls — you see what was delegated and what came back, not a full second conversation. Delegation rules and the loop-prevention model live on [Agent delegation](/platform/agents/delegation). ## When to reach for each shape | Use … when | Chat | Projects | Conversations | | ------------------------------------------------- | ---- | -------- | ------------- | | Personal task, one-off question | ✓ | | | | Shared workspace across a team, recurring threads | | ✓ | | | Inbound from a customer channel (email, webhook) | | | ✓ | ## Where this fits Agents in Chat is the user-facing half of the agents story — what the picker does, what shows up, how stickiness works. The build-facing half is [Agent concepts](/platform/agents/concepts): the four knobs that determine what an agent does once picked. If you came here to build the agent you wish were in the picker, that is the next read. # Arena Mode Source: https://tale.dev/docs/platform/chat/arena-mode Arena Mode runs the same prompt against two models at once and asks you which reply is better. The verdict feeds the org's feedback analytics; over time, the data tells which model the team actually prefers for which kind of question, separate from anyone's gut feel. Reach for Arena when picking a model has been a debate rather than a decision — comparing replies side by side breaks the deadlock with evidence rather than opinions. For ordinary work the regular model picker is enough; Arena's value is the verdicts it produces, not the comparison view itself. ## How Arena renders Open the composer's plus menu and pick **Arena Mode** — the composer sprouts two model pickers labelled **Model A** and **Model B**. Sending a message runs both models in parallel; the screen splits and each reply streams into its own column. Once both finish, a verdict row appears under the columns with four buttons: **A is better**, **B is better**, **Tie**, **Both bad**. <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.](/images/platform/chat-arena-split.webp) </Frame> <Note> Arena needs a specific agent — pick one instead of **Auto** in the agent picker before enabling it. </Note> ## Picking the contenders The two pickers are independent — any chat-tagged model the agent's policy allows is fair game on each side. Picking the same model on both sides is allowed (useful for testing temperature differences if the agent exposes that), but most comparisons span vendors or sizes. The agent's instructions, knowledge, and tools apply to both columns; only the underlying model differs. ## Casting a verdict The verdict is single-click. **A is better** and **B is better** are self-explanatory; **Tie** is for when both replies are roughly equally good; **Both bad** is for when neither is acceptable. The button you click records the verdict and resolves the chat to the winning column — the next message you send goes to that model only. Picking **Tie** or **Both bad** leaves both columns active for one more round. ## Where verdicts surface Verdicts roll up into [Feedback analytics](/platform/admin/governance/feedback-analytics) under **Arena verdicts**, alongside a **Top Model Matchups** table that ranks pairings by win rate. The data is org-scoped, not per-user, so a small team's verdicts can outweigh a large team's defaults when an admin uses the table to set the org's default model. ## When to reach for it | Use … when | Arena Mode | Regular model picker | | ---------------------------------------------------------------- | ---------- | -------------------- | | You are deciding which model to default to | ✓ | | | You suspect a model regression after an upgrade | ✓ | | | You already know which model you want; you just want a reply now | | ✓ | | The query is short and ordinary | | ✓ | ## Where this fits Arena is the lightweight feedback loop on top of model choice. The heavier surface is [Feedback analytics](/platform/admin/governance/feedback-analytics) — that is where the verdicts you cast become a chart someone uses to argue about defaults. If you are the one who will read the chart later, run a handful of Arena rounds before reading the chart; the verdicts you cast yourself will tell you whether the table's framing matches your experience. # Attachments Source: https://tale.dev/docs/platform/chat/attachments Attachments let a chat reference a file without bouncing you to another tab. You paste, drag in, or pick **Add photos & files** from the composer's plus menu; the file rides along with the message and Tale routes it to the right pipeline. Most file types land verbatim in the model's input; large or structured files are indexed and excerpted. This page covers the upload mechanic on the composer only. Documents uploaded into [Knowledge](/platform/knowledge/documents) follow a separate flow with persistent indexing — chat attachments are scoped to the chat that received them. ## A worked upload Paste a PDF into the composer. The composer surfaces a chip with the filename and a spinner; the chip becomes **Uploaded** once the file has landed on Tale's storage. **Send** the message, and the agent receives an extracted-text view of the PDF inline with your prompt. If the file is larger than the inline-context budget, Tale indexes it and the agent reads chunks on demand via its retrieval tool. ## Supported types Three families: **images**, **structured documents** (PDF, DOC/DOCX, ODT, XLS/XLSX, PPT/PPTX), and **text-like files** (plain text, markdown, source code, CSV, JSON, YAML). Images go to the vision model the chat is using; the model picker must be on a vision-capable model or the image will silently drop. Structured documents are extracted to text — diagrams, scanned pages, and embedded objects are best-effort. Text-like files land verbatim. ## Where uploads live Each attachment is stored in Tale's object store and bound to the chat that received it, and it is also copied into the chat's sandbox workspace at `/user/uploads/<name>`. That second copy is what the agent's `file_read`, `file_list`, and `run_code` tools operate on — the real bytes, not just the extracted-text view that rides inline with your prompt. Deleting the chat moves the attachments into [Trash](/platform/admin/governance/trash) with the message history; restoring brings them back. There is no separate "chat attachments" library — to share a document across many chats, upload it to [Knowledge](/platform/knowledge/documents) and bind it to an agent. ## RAG versus verbatim Small text files and structured documents under the agent's inline budget are pasted verbatim. Larger ones are chunked, embedded, and indexed; the agent retrieves the relevant chunks at reply time and cites them. The boundary depends on the model — long-context models swallow more whole. When the agent retrieves from an attachment rather than reading it whole, the citations point to chunk ranges in the original file. ## Referencing knowledge documents with @ <Frame caption="Typing @ opens the knowledge-base picker over the composer."> ![The chat composer with an at-sign typed and the knowledge-base picker open, listing three indexed text documents.](/images/platform/chat-mention-picker.webp) </Frame> Typing `@` in the composer opens a picker over the org's indexed knowledge, split into a **Documents** section and a **Folders** section. Type to filter by name; `@file` pins one document under a **Knowledge** chip, and `@folder` pins a folder and everything indexed under it under a **Folder** chip. On send, Tale checks your access, scopes that reply's retrieval to exactly the pinned items — a folder expands to its subtree's files — and injects the relevant passages even when the agent's knowledge mode is off, since an explicit mention outranks the agent's retrieval configuration. Up to five items, documents and folders combined, can be pinned per message. The chips are the source of truth: deleting the `@Title` text from the message does not unpin the reference — remove the chip instead. The picker only offers documents that have finished indexing and that your teams can access. Inside a project chat it also lists that project's own files and folders, ranked first; a project's files stay scoped to the project and never surface in the `@` picker of a chat outside it — see [Manage project files](/platform/projects/manage-files). The reference is per-message; a follow-up without mentions falls back to the agent's normal knowledge scope. ## Where this fits Attachments are the lightweight, chat-scoped way to bring a file into a reply. The heavyweight, org-scoped equivalent is [Documents](/platform/knowledge/documents) — same indexing pipeline, but bound to agents instead of a single chat. The page worth reading next depends on what you are trying to do — if the file matters once, attach it here; if it will matter again, upload it to Knowledge and let an agent reference it from every chat. # Chat basics Source: https://tale.dev/docs/platform/chat/basics This page is the mental model for everything in the Chat tab. It names the parts of the composer, traces a message from key-press to streamed reply, and explains how a chat is stored once it lands — read it once and the rest of the chat pages are variations on the same flow. <Frame caption="The Chat tab with a streamed reply above the composer."> ![A chat thread showing a user question about onboarding feedback and an assistant reply containing a markdown table of three themes.](/images/platform/chat-thread-reply.webp) </Frame> ## The composer The composer is the input strip at the bottom of the screen. Three controls matter: the agent picker on the left, the model picker beside it, and the message field with send on the right. Attachments come in via paste, drag-and-drop, or the attach control — see [Attachments](/platform/chat/attachments) for what is accepted. <Frame caption="The composer's controls — the message field, the agent and model pickers, and send."> ![The empty chat composer, its placeholder inviting a question about contacts, products, or documents, above a toolbar row carrying the attach and prompt-library controls, the agent and model pickers, and the mute, microphone, and send buttons.](/images/platform/chat-composer.webp) </Frame> ## Picking an agent The agents picker filters by name as you type; the default is an agentless **Assistant** that uses the org's default chat model and no extra knowledge or tools. Picking an agent before the first message makes the agent sticky for the whole chat; picking one mid-chat applies from the next message onward. <Note> There is no "back to no agent" toggle — pick **Assistant** to revert. The full rules live in [Agents in chat](/platform/chat/agents-in-chat). </Note> ## Picking a model The model picker lists what the agent (or the org, when no agent is picked) allows. Each model carries a tag — **Chat**, **Vision**, **Image generation**, **Embedding** — that signals what it is good for. **Auto** picks the agent's primary; when the primary is rate-limited or unavailable, Tale falls back through the agent's failover order. <Warning> Picking a non-vision model when the message includes an image silently drops the image — the reply reads as if the image was never sent. </Warning> ## Reading the reply The reply streams in token by token. When the agent reasons before answering, a collapsible thinking line appears above the reply. Tool calls render as collapsed boxes you can expand to read what the agent did; **Run code** output lands in the Canvas on the right, as **Code output** in its file tree. When the agent retrieves knowledge, citations attach to the sentences they support — hovering over a citation shows the source title, clicking opens the source. The agent's instructions never appear in the rendered reply; they sit one layer down, shaping behaviour rather than text. ## Questions from the agent An agent with the human-input tool can pause mid-task and ask you something — a **Question** card appears in the chat with the fields the agent needs, and generation waits until you answer. Fill the form and click **Submit response**, or click **Reply differently** to push back in free text instead. If your answer was wrong or incomplete, click **Edit response** on the answered card — the form reopens prefilled, and **Update response** re-runs the agent with the corrected answer superseding the old one. The card keeps every previous answer: flip through the versions with the arrows next to the response, the way edited messages work. ## Conversations versus chats Within Chat, the unit is a **chat** — that is the word every button and toast uses. The data model behind it is called `threads`, and the URL slug is `threads/$threadId`; the docs follow the UI and say "chat" in body prose. The customer-channel inbox an installed email automation adds is a different surface — a conversation there is a customer thread, not a chat; see [Built-in automations](/platform/automations/builtin) for the inbox sense. ## History and search **Show chats** above the composer opens the history sidebar — every chat you can resume in this org, newest first; selecting one opens the full transcript. Searching there filters by title; full-text search across message bodies is a per-chat operation, not org-wide. Renaming a chat sets a custom title that overrides the model-generated one; deleting a chat moves it into [Trash](/platform/admin/governance/trash), where retention sweeps it after the grace window. ## Where this fits Chat basics is the page everything else in this section refines: [Agents in chat](/platform/chat/agents-in-chat) goes deeper on the picker, [Attachments](/platform/chat/attachments) on what the upload does, [Voice mode](/platform/chat/voice-mode) on the STT and TTS handoffs around the same composer. If you came here to build an agent rather than use one, jump to [Agent concepts](/platform/agents/concepts) — the four-knob mental model is the foundation every chat with an agent depends on. # Canvas pane Source: https://tale.dev/docs/platform/chat/canvas-pane The **Canvas** is a second pane that opens to the right of the chat thread. It appears when the reply contains content the linear thread cannot hold well — a long code block, a Mermaid diagram, a structured document, a runnable Python script. Inline replies stay short and readable; everything else moves out of the way. The Canvas is not a richer composer, and it is not a place you edit by hand. It is a live view of the chat's workspace — the files the agent writes, the files you upload, and the files code runs produce — surfaced without your having to ask. ## What the Canvas is The Canvas opens automatically the first time a reply produces Canvas-worthy content. It has two parts: a file tree on the left and a viewer on the right. The tree groups the chat's workspace files by where they came from — **AI files** the agent wrote (`/user/code`), **Uploaded** files you attached or `@`-pinned (`/user/uploads`), and **Code output** a run produced (`/user/output`); empty groups are hidden. Pick a file and it opens in the viewer, where you toggle between **Source** and **Preview** to read raw code or see the rendered result, and **Download** saves that file. ## When it auto-opens The Canvas opens for several render kinds the inline thread would crowd: **Code** (any language), **HTML**, **Mermaid** diagrams, **SVG**, long **Markdown** documents the agent produced, and runnable scripts — **Python (sandbox)**, **Node (sandbox)**, **Script (sandbox)**. `run_code` executes over the chat's shared workspace — it reads scripts the agent wrote under `/user/code` and harvests whatever the run leaves in `/user/output`, so results surface as **Code output** rows in the file tree, not just beside the script; a run can also install packages on their own as a separate step, showing **Installing dependencies** while it works. Only agent-written and code-output files auto-open the Canvas — files you upload appear in the tree but do not grab the screen. Short snippets the inline thread can hold do not trigger the Canvas — a twenty-line script renders inline with its own **Copy** control, as below. <Frame caption="A short script stays inline — the Canvas is for output that outgrows the thread."> ![A chat reply containing a syntax-highlighted Python code block rendered inline with a Copy button, without the Canvas pane opening.](/images/platform/chat-code-reply.webp) </Frame> ## Editing in the Canvas The Canvas is a render surface for whatever the agent produced. Editing the rendered content means asking the agent to revise it — a follow-up message in the thread ("change the timeout to 30 seconds", "make the diagram horizontal") triggers a new generation that replaces the Canvas content. There is no direct-edit mode; the agent owns the files it writes, and the files you upload stay exactly as you sent them. ## Persistence across the chat The Canvas content is part of the chat, not a separate file. Reopening the chat later reopens the Canvas with the latest content; switching to another chat closes the Canvas pane until that chat produces or carries Canvas content of its own. Sharing the chat with **Share chat** carries the Canvas across — the viewer sees the same Source / Preview toggle, in read-only mode. ## Where this fits The Canvas is the answer to "what happens when the reply is too big for the thread". It composes with everything else in Chat — agents, attachments, voice, shared chats — without those features needing to know about it. The next read that sometimes matters: [Build a custom tool](/tutorials/developer/build-a-custom-tool) walks an agent that produces runnable Python in the Canvas, end to end, on a fresh instance. # Deep research Source: https://tale.dev/docs/platform/chat/deep-research Deep research is a composer mode that hands a question to a specialised **Researcher** agent. The agent plans the work as a list of sub-questions, searches the open web with Tavily, reads the most promising pages, tracks progress in a to-do card you can watch in real time, and finishes with a PDF report that cites every source it used. Reach for it when the question is open-ended, the answer needs evidence, and you would otherwise spend an hour with twenty browser tabs. This page covers the Deep research surface end to end — when to pick it, what the flow looks like, the budget that keeps it from running forever, and where the cited sources come from. The agent's mechanic is the same shape as every other Tale agent (see [Agent concepts](/platform/agents/concepts)); what is unusual here is the live to-do plan and the Tavily integration that drives the searches. ## When to reach for it Deep research beats a plain chat for questions where the value is not the model's existing knowledge but the assembly of recent, sourced information. Three signals it is the right mode: - The question is open-ended ("what is the current consensus on…", "compare the top three…"). - You want citations — a quote without a URL is a guess. - You are happy to wait two to ten minutes for a written report instead of a chat reply. For narrow factual questions ("what is the capital of Senegal") plain chat is faster and just as accurate. For questions about your own data ("what did the customer say in last Tuesday's call") an agent with [Knowledge](/platform/agents/knowledge) bindings is the right shape — Deep research only reads the open web, not your knowledge base. ## Open Deep research Open the composer's plus menu — modes live under its **Modes** header, and **Deep research** appears there once the Researcher agent is available. Pick it and the composer switches into the Researcher agent. Type the question and send. The reply pane changes from the usual streaming text to a **research plan** card with three to seven to-do items the agent has chosen as sub-questions. <Frame caption="Modes live in the composer's plus menu; entries appear as their requirements are met."> ![The composer's plus menu open, showing an Add photos and files entry and a Modes section listing Arena Mode.](/images/platform/chat-composer-menu.webp) </Frame> The mode is available when an Editor or above has bound the **Tavily** integration under [Settings > Integrations](/platform/integrations/overview); without Tavily, the menu entry names the missing integration and clicking it opens the integration settings. ## The research plan The plan is a list of `pending` to-do items the agent generated from your question. For complex questions the agent pauses after the first plan and asks you to confirm — a **Proceed with this plan?** card appears with a yes/no field. Click yes to start; click no and the agent does not run further. Trivial questions skip the confirmation. Once running, the agent works the to-dos one at a time: 1. Sets the current to-do to `in_progress`. 2. Searches Tavily up to three times for that to-do. 3. Reads up to two of the most promising URLs in full via Tavily's extract operation. 4. Sets the to-do to `done` with a one-sentence finding. The card updates live as each step lands. You can watch the model's reasoning shape itself; if a new sub-question surfaces mid-run, the agent adds it to the list. ## Searches and extracts Tavily is the open-web search provider behind Deep research — its API is optimised for LLM agents and returns search hits with cleaned snippets and per-result scores. Two operations matter: - **search** — natural-language query with depth (`basic` or `advanced`), topic (`general` or `news`, with a `days` window for recency), and an optional domain allowlist or blocklist. - **extract** — fetches the cleaned main-article text for one to five URLs. The agent calls this on the two best hits per to-do when a snippet is not enough. Tavily's free tier is 1000 calls per month; paid plans unlock `advanced` depth on search and the extract operation. The setup steps live on the integration's setup card in **Settings > Integrations**. ## Per-run budget Deep research caps a run at: - **3 searches + 2 extracts per to-do.** The integration wrapper rejects calls beyond this. - **40 reasoning steps total** across the whole run. - **25 minutes wall-clock.** After that the agent stops and synthesises with whatever it has. - **60 integration calls total per run** as a hard ceiling. Hitting any cap stops the search phase and pushes the agent into synthesis. If you need more, run the question again with a tighter scope or break it into two questions. ## The PDF report When every to-do is `done` (or cancelled, or the budget hit a wall), the agent calls the **pdf** tool once to produce a single structured report: - **Conclusion** — one to three sentences answering the question directly. - **Key points** — three to seven bullets, each carrying at least one inline citation to a Tavily source. - **Details** — the longer analysis grouped by sub-question. - **Sources** — a deduplicated list of every cited URL. The PDF arrives as an attachment card in the chat. The agent does not paste the report into the message body — the card is the deliverable. A short confirmation line in your language ("Research complete — see the attached PDF for the full report.") points at the card. For Chinese, Japanese, and Korean reports the PDF renderer's font set is incomplete; in that case the agent emits the same structured report directly in chat and notes that an English-translated PDF is available on request. ## Failure cases - **Tavily not connected.** The agent emits a one-liner asking an Editor to connect Tavily in **Settings > Integrations** and stops. - **Tavily quota exhausted.** The integration returns `INTEGRATION_BUDGET_EXHAUSTED` and the agent moves to synthesis with whatever it has. Free tier hits this around the thousandth call of the month. - **A specific URL fails to extract.** The relevant to-do is marked `failed` with a reason; other to-dos keep running. - **Your budget runs out.** The run stops and the agent synthesises. The card shows which to-dos were skipped. ## Where this fits Deep research is the heaviest end of the chat composer — it does in ten minutes what an analyst would do in an afternoon. Pair this page with [Agent concepts](/platform/agents/concepts) (the four-knob model the Researcher agent is built on) and [Integrations overview](/platform/integrations/overview) (where Tavily sits alongside the other integrations the agent toolbelt can reach). If you want to build your own research-style agent rather than use the shipped one, [Create an agent](/platform/agents/create) walks the agent build end to end. # Chat Source: https://tale.dev/docs/platform/chat/overview Chat is the everyday entry point to Tale. You open it, pick an agent (or none), type, and a reply streams back — citations, tool calls, and all. Most users spend more time here than in any other tab; everything else in Platform exists to feed Chat with something useful or to govern what it does. <Frame caption="A chat with a streamed reply — the surface every other feature serves."> ![A chat thread showing a user question about onboarding feedback and an assistant reply containing a markdown table of three themes.](/images/platform/chat-thread-reply.webp) </Frame> ## The parts of the screen The composer at the bottom carries the agent picker, the model picker (**Auto** lets Tale pick for you), and the message field. **New chat** in the sidebar starts a fresh chat; **Show chats** opens the history of every chat you can resume. The Canvas opens to the right of the thread when the agent produces something the inline view cannot hold — long code, a diagram, a structured document. ## Pages in this section <CardGroup cols="2"> <Card title="Chat basics" icon="message-circle" href="/platform/chat/basics"> What happens between hitting send and the reply landing — composer, model resolution, streaming, citations. </Card> <Card title="Attachments" icon="paperclip" href="/platform/chat/attachments"> Supported file types, where uploads land, when content gets indexed versus pasted verbatim. </Card> <Card title="Agents in chat" icon="bot" href="/platform/chat/agents-in-chat"> Picking agents, one-shot versus sticky, switching mid-thread, sub-agent calls. </Card> <Card title="Arena Mode" icon="swords" href="/platform/chat/arena-mode"> Side-by-side model comparison, and how verdicts roll into feedback analytics. </Card> <Card title="Voice mode" icon="mic" href="/platform/chat/voice-mode"> Speaking instead of typing — the STT and TTS handoffs and the privacy boundary. </Card> <Card title="Shared chats" icon="share-2" href="/platform/chat/shared-threads"> Sharing a chat with the rest of the org, forking a shared chat into your own. </Card> <Card title="Starters and prompts" icon="list-plus" href="/platform/chat/starters-and-prompts"> Agent conversation starters and the prompt library. </Card> <Card title="Canvas pane" icon="panel-right" href="/platform/chat/canvas-pane"> When the Canvas opens, and what gets a Canvas versus inline rendering. </Card> </CardGroup> ## Where this fits Chat is the surface every other Platform feature ultimately serves. Agents shape its replies, Knowledge feeds its citations, Approvals interrupt it for human checks, Conversations is a sibling inbox for customer channels rather than your own threads. The page worth bookmarking first is [Chat basics](/platform/chat/basics) — once you understand the composer-to-reply path, every other chat page reads as a variation on it. # Shared chats Source: https://tale.dev/docs/platform/chat/shared-threads Sharing a chat creates a link that anyone in your organization can open. The viewer sees the full transcript in read-only mode; they cannot reply, but they can fork the chat into one of their own and continue from there. The mechanic is light enough to use casually — share a question and its answer the way you would share a document. This page covers the sharing surface end to end: enabling sharing, who the link works for, the read-only view, and the fork gesture that turns "I want to follow up" into a new chat. ## Sharing a chat Click **Share** in the chat's header. The **Share chat** dialog offers **Enable sharing** as a toggle and, once enabled, the share link with **Copy link** and **Preview** — the latter opens the read-only view the recipient will see. Paste the link into the channel your team uses. <Frame caption="The Share chat dialog — org-scoped link, copy, and preview."> ![The Share chat dialog over a chat, showing the Enable sharing toggle switched on, the share link, and Copy link and Preview buttons.](/images/platform/chat-share-dialog.webp) </Frame> **Anyone in your organization with the link can view this chat** — the link is scoped to the org, not the wider internet. Disabling sharing later invalidates the link; visitors land on a not-found page. ## What the viewer sees The viewer opens the link and lands on the chat with a banner: **You are viewing a shared chat in read-only mode**. The transcript reads exactly as the author sees it, including tool calls and citations. The composer is replaced with a single hint — **Sending a message will create your own copy of this chat** — that is the only path forward. ## Forking a shared chat The viewer's only write action on a shared chat is **Fork this chat**. The fork creates a new chat owned by the viewer, with the full transcript copied across as context. The original is unchanged; the fork has no link back to the original beyond the messages it inherits. From the viewer's side the fork is now an ordinary chat — sticky agent picks, model picks, and tools all behave as they would in any chat the viewer started themselves. ## When the link goes stale Disabling sharing invalidates the link. Deleting the source chat sends it to [Trash](/platform/admin/governance/trash) and the link breaks; restoring the chat from Trash does not restore the link — the author re-enables sharing if it is needed again. Existing forks are unaffected by either action because they are independent chats. ## Where this fits Shared chats are the lightweight way to hand a chat to a teammate without leaving the product. The heavier-weight alternative is bringing the teammate into a [Project](/platform/projects/overview) where chats, files, and agents are shared by default. Sharing is for one-off handoffs; a Project is for ongoing collaboration on the same work. # Starters and prompts Source: https://tale.dev/docs/platform/chat/starters-and-prompts A fresh chat shows two surfaces beyond the composer: the agent's **Starters** (one-tap example prompts) and the **Prompt library** (your saved prompts). Both turn the empty-screen problem — "what should I even ask" — into a single click that drops working text into the composer. This page covers both surfaces. They live near each other in the UI for a reason: starters are the agent author's curated entry points, the library is your personal stash, and most teams end up using both together. ## Conversation starters <Frame caption="A fresh chat with the picked agent's starters — one tap drops the text into the composer."> ![The empty new-chat screen showing the Assistant's four conversation starters above the composer.](/images/platform/chat-starters-empty.webp) </Frame> Every agent can ship up to four **Starters** — short example prompts the agent's author has decided make good entry points. They appear on the empty-chat screen when the agent is picked; tapping one drops the starter text into the composer and lets you edit before sending. Starters belong to the agent, not the chat — the same agent shows the same starters everywhere. Agent authors maintain starters on the **Starters** tab of the agent's editor; see [Conversation starters](/platform/agents/conversation-starters) for the author side. Members see what the author published; there is no per-user override. ## The prompt library The **Prompt library** is your personal collection of reusable prompts. Save the message you are about to send with **Save prompt**; recall it later with **Prompt library** on the composer. Prompts can carry placeholders the library prompts you to fill in at insert time, so a "translate the following into German" template becomes a one-tap workflow. Prompts you save are private by default. Sharing a prompt with the org makes it visible in everyone's library; the org's prompt list lives in [Prompt library](/platform/workspace/prompt-library) (the workspace page) for browsing and tagging. ## Categories Both starters and prompts can carry a category — a short tag like `Sales`, `Support`, `Marketing` that groups them in the picker. Categories are org-defined and managed under settings; an agent or prompt without a category sits in the default bucket. ## Where this fits Starters and prompts are the empty-screen scaffolding around Chat. The library half overlaps with [Prompt library](/platform/workspace/prompt-library) — same data, different surface. Starters live on the agent and are managed from the agent's [Conversation starters](/platform/agents/conversation-starters) page. The next read depends on which side you are on — author or user. # Voice mode Source: https://tale.dev/docs/platform/chat/voice-mode Voice mode turns the composer into a microphone. You speak, Tale transcribes, the agent replies in text, and the reply is read back out loud. The whole loop is hands-free — useful when you are walking, driving (legally), cooking, or tired of typing. The composer's speech path crosses two model providers (speech-to-text, then text-to-speech) and one or two agent calls in between. Knowing which provider holds which piece of the audio is the difference between "this is convenient" and "this is reckless" for your organisation's data. ## How voice mode runs Tap the microphone icon on the composer and recording starts; tap again to stop. Tale uploads the audio clip, the speech-to-text model transcribes it, and the transcript becomes the next message in the chat — exactly as if you had typed it. The agent answers in text; once the reply is complete, Tale routes it to a text-to-speech model and plays the audio back. While the reply is streaming, **Stopped** ends playback early; **Play voice output** re-plays the last reply. ## STT and TTS handoffs Two model picks matter, and they are configured separately from the chat model. **Speech-to-text** runs once per spoken message — the audio is uploaded, transcribed, and the transcript is what the agent sees. **Text-to-speech** runs once per reply — Tale chunks the reply into voice-output segments and streams audio back. The agent itself is unchanged; voice mode is a wrapper around the same composer. ## Voice picking Each agent can pin a preferred voice in its settings; without a per-agent pick, voice mode uses the org default. Voices are tied to specific TTS providers — switching the provider switches the available voices. If a chat uses an agent whose voice provider is no longer configured, Tale falls back to the org default voice rather than failing the reply. ## Privacy boundary The audio clip you record leaves your device. It is uploaded to Tale's storage, sent to the speech-to-text provider you configured, and the transcript is kept in the chat history alongside the typed messages. The audio itself is retained per the org's retention policy. Replies go out to the text-to-speech provider as plain text; the audio response is streamed to your device and not stored on disk by default. <Warning> Organisations with strict data-out-of-region rules should pick STT and TTS providers in the same region as the rest of the stack — see [Data residency](/cloud/data-residency). </Warning> ## When voice beats text Voice is faster than typing for short, conversational questions and dramatically slower than typing for code, lists, or anything you would copy out. Voice replies cap out at a chunk limit — long replies stop reading partway through and surface a notice. Reach for voice when the answer will be heard once and forgotten; reach for text when the answer needs to be skimmed or saved. ## When to reach for it | Use … when | Voice mode | Text | | -------------------------------------------------- | ---------- | ---- | | You are hands-busy and want a quick fact | ✓ | | | The reply will be a long list or code block | | ✓ | | The agent's reply will inform a later written task | | ✓ | | You are practising a language and want to hear it | ✓ | | ## Where this fits Voice mode is one of three "input shape" options on the same composer: text (the default), attachments, and voice. The privacy story matters most here because two extra providers touch the data, so the page worth reading next is [Data residency](/cloud/data-residency) on Cloud or [Configuration → providers](/self-hosted/configuration/providers) on self-hosted, depending on which edition you run. # Developer Source: https://tale.dev/docs/platform/developer/overview Developer is the in-app surface for the people who wire Tale to the rest of their stack. It groups the four levers that let external code talk to Tale and Tale talk to external code: API keys for the REST surface, custom tools that extend an agent's reach, agent webhooks for inbound triggers, and MCP servers for the external-process bridge. People with the Developer role see this menu; Members and Editors do not. This overview names what each page covers and points to the deeper reference. Developer-role users typically land here on their first day, set up the credentials and tools they need, and come back when they extend the stack — adding a new MCP server, rotating a key, registering a new webhook. ## What Developer covers The Developer surface sits beside the rest of the org's settings but with a narrower audience. It assumes you know what a REST API is, what a webhook looks like, and what an MCP server does — the pages do not re-explain the underlying concepts; they explain how Tale exposes them. The same surface in the Cloud and self-hosted tabs differs only in deployment shape; the UI here is identical. The configuration-file equivalents of some of these features (env vars, JSON configs for custom tools) live one tab over in the self-hosted documentation. ## Pages in this section <CardGroup cols="2"> <Card title="API keys" icon="key" href="/platform/admin/api-keys"> Wire a script, a cron job, or an internal service to Tale's REST API. Shared with Admin under Settings > API keys. </Card> <Card title="MCP servers" icon="server" href="/platform/integrations/mcp-servers"> Register an external MCP-protocol process and pick which of its tools the org's agents may call. </Card> <Card title="Agent webhook triggers" icon="webhook" href="/platform/agents/webhook-triggers"> Fire a specific agent from an external system on an inbound POST. </Card> <Card title="Agent tools" icon="wrench" href="/platform/agents/tools"> Extend an agent's toolbelt with a custom tool the org's agents can call. </Card> </CardGroup> ## Where this fits Developer is the bridge between Tale and the rest of the codebase the org runs. The natural first read depends on what you came to wire — for outbound (something inside Tale calls outside) [Agent tools](/platform/agents/tools) and [MCP servers](/platform/integrations/mcp-servers); for inbound (something outside calls into Tale) [API keys](/platform/admin/api-keys) and [Agent webhook triggers](/platform/agents/webhook-triggers). # Editor Source: https://tale.dev/docs/platform/editor/overview Editor is the build surface of Tale. Where Member is the role that runs the product and Admin is the role that governs it, Editor is the role that creates the things everyone else uses — agents, projects, automations, the documents and structured data the knowledge base holds, the prompts saved for the team. People with the Editor role see the full set of build tabs without the admin governance surface and without the developer-only levers. This overview names what an Editor does, where they do it, and which pages cover each piece. Editors typically land here on their first day, build out the org's first useful agent and project, and come back to this tab whenever the next thing needs to be built. The role-and-permission story behind the tabs lives on [Members and roles](/platform/admin/members-and-roles). ## What Editor covers The work an Editor does falls into four buckets: building **agents** (instructions, knowledge bindings, tools, models), curating the **knowledge base** (uploading documents, maintaining customers, products, vendors, websites), authoring **automations** (workflows with triggers, steps, and approval gates), and bundling **projects** (file sets, scoped agents, project instructions). Each bucket has its own section in Platform; the Editor tab is the index across them. Editors share the build surface with Developers — Developers also see all four buckets and can do everything an Editor can, plus the API and integration plane. Reach for an Editor when the day-to-day work is content and configuration; reach for a Developer when the work crosses into code or external systems. ## Pages in this section The Editor surface is the same surface the per-area sections of Platform document. What follows is the index across them. <CardGroup cols="2"> <Card title="Agents" icon="bot" href="/platform/agents/concepts"> The four-knob mental model an Editor builds every agent from. </Card> <Card title="Automations" icon="workflow" href="/platform/automations/concepts"> Workflows, triggers, steps, executions. </Card> <Card title="Knowledge" icon="library" href="/platform/knowledge/overview"> The documents and structured-data area an Editor curates. </Card> <Card title="Projects" icon="folder-open" href="/platform/projects/overview"> The shared workspace an Editor bundles around a customer or a launch. </Card> <Card title="Prompt library" icon="list-plus" href="/platform/workspace/prompt-library"> The saved-prompts area an Editor uses to keep recurring chat starters reusable. </Card> </CardGroup> ## Where this fits Editor is the role most teams have several of — the people who do the build work other roles consume. The natural first read on day one is [Agent concepts](/platform/agents/concepts), because the four-knob model is what every other build page assumes. The natural second is [Build your first agent](/tutorials/editor/first-agent-end-to-end) — it walks the four knobs end to end on a fresh instance. # Platform Source: https://tale.dev/docs/platform Platform is the canonical product reference: every user-visible feature in Tale, identical for Cloud and self-hosted. The pages here describe the UI someone clicks, the concept behind the UI, and the trade-offs between features that look similar. The section is organised by area, then by feature within an area. Most readers do not read it front to back — they land here from a search result or a link from a tutorial, and the page they landed on should answer the question they brought. ## Feature areas <CardGroup cols="2"> <Card title="Chat" icon="message-circle" href="/platform/chat/overview"> The everyday entry point — threads, agents in chat, attachments, arena mode, voice mode, the Canvas pane, sharing. </Card> <Card title="Projects" icon="folder-open" href="/platform/projects/overview"> Shared workspaces that bundle files, instructions, threads, and project-scoped agents. </Card> <Card title="Agents" icon="bot" href="/platform/agents/concepts"> Instructions, knowledge, tools, model — plus skills, workers, versioning, and webhook triggers. </Card> <Card title="Automations" icon="layout-grid" href="/platform/automations/concepts"> Installable bundles of integrations, agents, skills, and a workflow — the catalog, the install wizard, the editor and triggers behind each one, and the run history it leaves. </Card> <Card title="Knowledge" icon="library" href="/platform/knowledge/overview"> Documents, customers, products, vendors, websites — the structured-data model agents cite. </Card> <Card title="Approvals" icon="check-check" href="/platform/approvals/concepts"> Inline cards, workflow gates, and the approver pool that keeps humans in the loop. </Card> <Card title="Prompt library" icon="list-plus" href="/platform/workspace/prompt-library"> Saved prompts with personal, team, and global visibility, plus version history. </Card> <Card title="Models" icon="cpu" href="/platform/models"> The model catalog behind every picker — capability tags, defaults, and the shipped list. </Card> <Card title="Integrations" icon="plug" href="/platform/integrations/overview"> Third-party SaaS pairings and MCP servers. </Card> </CardGroup> ## Set up your first day Four role-indexed entries map the same features from the reader's side of the desk — what a Member, an Editor, a Developer, or an Admin actually touches on day one. <CardGroup cols="2"> <Card title="Member" icon="user" href="/platform/member/overview"> Chat, knowledge, personal preferences — the surface most people in most orgs use. </Card> <Card title="Editor" icon="pencil-ruler" href="/platform/editor/overview"> The build surface — agents, knowledge curation, automations, projects. </Card> <Card title="Developer" icon="terminal" href="/platform/developer/overview"> API keys, custom tools, webhooks, MCP servers — wiring Tale to external code. </Card> <Card title="Admin" icon="shield" href="/platform/admin/overview"> Organization settings, providers, branding, integrations, and the governance sub-tree. </Card> </CardGroup> ## Where this fits Platform is the gravity well — Cloud and self-hosted both link into it for feature documentation, and every tutorial cites pages here for the underlying concepts. The page worth bookmarking on your first day is [Agents → concepts](/platform/agents/concepts) — almost every other product page assumes the four-knob mental model that page builds. # MCP servers Source: https://tale.dev/docs/platform/integrations/mcp-servers An MCP server is an external process that exposes tools to Tale's agents over the Model Context Protocol. Where an [integration](/platform/integrations/overview) is a vendor-specific connector Tale ships, an MCP server is a generic bridge anyone can host — an internal API, a vendor without a connector, a script that computes something Tale's built-in tools cannot. You host the server; Tale only talks to it. <Frame caption="The Add MCP server form — a connection and an authentication method are the whole registration."> ![The Add MCP server dialog under Settings API MCP, filled in for a support-tickets server — display name Support Tickets, a one-line description, Streamable HTTP as the transport type, the server URL, and an authentication method of None — over the MCP page, where an Internal Wiki server is already registered.](/images/platform/settings-mcp-add-dialog.webp) </Frame> ## Registering a server Open **Settings > API > MCP** and click **Add MCP server**. The form takes: - **Name** and **Display name** — the identifier, and the label agents and approval cards show. - **Transport type** — **Streamable HTTP**, **SSE**, or **stdio**. The HTTP transports take a **URL** — the form flags a malformed one inline before you can save; stdio takes the command Tale spawns. - **Authentication** — **None**, **API Key**, or **OAuth 2.0** (token URL, client ID and secret, scopes). - **Allowed agents** — which agents may bind to this server. The default is no agents; reach for **All agents** only when the server is generic enough that every agent benefits. **Save server**, then use **Test connection** on the row to verify the handshake — the row's status shows **Connected**, **Disconnected**, or **Error** with the upstream message. ## The discovered tools Once connected, Tale fetches the server's manifest and lists it as **Discovered Tools** — each tool's name, description, and whether the server flags it **Requires approval**. Flagged tools ask in chat every time an agent calls them, with the exact arguments shown on the card; unflagged tools run like any built-in tool. <Warning> Every MCP tool widens what your agents can reach, and the approval flags come from the server's author — connecting a server means accepting its tool contract. Read the discovered list before pointing agents at a server you did not write. </Warning> ## Using it from agents A registered, active server's tools join the toolbelt agents can call; the request travels through Tale to your server and the reply comes back into the conversation. The server can also expose resources and prompts where its author implements them — tools are the common surface. ## Deactivating and removing Each server row can be deactivated — its tools drop out of agent toolbelts until you activate it again, with the registration kept. Deleting the server removes the registration entirely after a confirmation; re-adding it later is a fresh registration with a fresh manifest fetch. ## MCP server or integration Both let an agent reach beyond Tale; the difference is who owns the connector. Integrations are vendor-specific, shipped, and maintained in the catalog; MCP servers are generic and yours to run. Reach for the integration when one exists for the target system; reach for MCP when you need the bridge to be your own code. ## Where this fits MCP is the open-ended extension surface of the agent toolbelt. The natural next reads are [Agent tools](/platform/agents/tools) for how tools surface on an agent, [Configure approvals](/platform/approvals/configure) for the flags that hold risky calls, and the [MCP server from scratch](/tutorials/developer/mcp-server-from-scratch) tutorial for building one end to end. # Integrations Source: https://tale.dev/docs/platform/integrations/overview Integrations are the bridges between Tale and the rest of your stack: agents call them as tools, workflows call them at steps, and the knowledge pipeline pulls documents through them. The org connects each one once under **Settings > Integrations**; from then on, anything in Tale can use it without re-authenticating. This overview names the shipped catalog and the two ways to extend it. <Frame caption="Settings > Integrations on the All integrations tab — the full catalog, each card one Connect away."> ![The Settings Integrations page showing a search field, an Add integration button, and a card grid of twelve services including Confluence, GitHub, Gmail, Slack, and Twilio.](/images/platform/integrations-catalog.webp) </Frame> ## The catalog The page has two tabs — **Connected** shows what the org already uses, **All integrations** the full catalog with a search field. Each card's description is the honest one-liner of what connecting buys you: | Integration | What it does | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Confluence** | Import Confluence Cloud pages into Tale's knowledge base. | | **Discord** | Post messages and manage channels in your Discord server. | | **GitHub** | Manage repositories, issues, and pull requests on GitHub. | | **Gmail** | Read, send, and organize email in Gmail. | | **Google Drive** | Import files from Google Drive into Tale's knowledge base. | | **IMAP / SMTP Mailbox** | Connect a private IMAP + SMTP mail server to the Inbox — no Gmail or Outlook account required; sending can go through a separate SMTP relay (Resend, SendGrid, Amazon SES, …) instead of the mailbox login. | | **Microsoft Outlook** | Manage Outlook mail, calendar, and contacts. | | **Shopify** | Sync products, customers, and orders from your Shopify store. | | **Slack** | Send messages and interact with channels in Slack. | | **Tavily** | Real-time web search and page extraction for AI research. | | **Microsoft Teams** | Send messages and manage channels in Microsoft Teams. | | **Twilio** | Send SMS and make voice calls with Twilio. | ## Connecting one Click **Connect** on a card. OAuth-backed services walk the vendor's consent flow; token-backed ones ask for the credential in an **Authentication** section. The detail view also lists the integration's operations — the ones badged **Requires approval** hold in chat until a person signs off, which is how outbound writes stay accountable ([Configure approvals](/platform/approvals/configure)). Documents imported through Confluence or Google Drive flow through the same indexing pipeline as direct uploads, and citations point back to the source — see [Documents](/platform/knowledge/documents). ## Extending beyond the catalog **Add integration** uploads a custom connector — a small package of `config.json`, a `connector.js` or `.ts`, and an icon (as a `.zip` or individual files, 1 MB total). The preview shows its operations, allowed hosts, and connector code before you install, and the result appears in the catalog like any shipped entry. When no connector fits and you can host the bridge yourself, register an [MCP server](/platform/integrations/mcp-servers) instead — a generic protocol surface rather than a vendor-specific connector. <Note> WebDAV is not in this catalog because it points the other way: it serves Tale's documents to your devices as a network drive. See [WebDAV](/platform/integrations/webdav). </Note> ## Where this fits Integrations are how agents act on the world outside Tale. For the agent author, [Agent tools](/platform/agents/tools) shows how an integration's operations surface as tools; for the approver, [Configure approvals](/platform/approvals/configure) is where the write operations are held; for the builder with no connector to reach for, [MCP servers](/platform/integrations/mcp-servers) is the open-ended alternative. # WebDAV Source: https://tale.dev/docs/platform/integrations/webdav WebDAV turns Tale's document store into a remote folder you mount like any shared network drive. The backing store is the same one the Document Hub shows — what you drop into the mounted folder appears in the UI, and vice versa. Everything you need is on one panel: **Settings > API > WebDAV** carries the connection details and the app-password generator. <Frame caption="Settings > API > WebDAV — the pre-filled connection details on top, the app-password generator below."> ![The WebDAV settings page showing a connection URL, a username field with the account email, an explanation that the password is a generated app-password, and an app-passwords table holding two entries — Design workstation and MacBook Pro, each with only its prefix and creation date — beside a Generate button.](/images/platform/settings-webdav.webp) </Frame> ## Generate an app-password The endpoint authenticates with app-passwords — short secrets you mint per device — because every WebDAV client stores its credential in the system keychain, and a scoped, revocable secret belongs there rather than your account password. Your account password does not work on this endpoint. Click **Generate**, label the password after the device (`MacBook Finder`, `ops-laptop rclone`), and copy it — use one per device; the full password is only shown once. Afterwards the table keeps only the label and a short prefix, enough to recognise the row when you revoke it. Generating requires the same capability that gates API keys; plain members ask an admin. For the username, use your Tale account email. Only the password is actually verified, but the email keeps audit rows readable and matches what client dialogs expect. ## Connect from your device The address is the URL from the panel — `https://<your-site>/dav/<orgSlug>/documents/`. <Tabs> <Tab title="macOS Finder"> Press **⌘K** (Connect to Server), paste the URL, and sign in with your email and the app-password. The share mounts in the sidebar; drag files in to upload, out to download, and rename or delete in place. The first listing of a large tree can take a few seconds. </Tab> <Tab title="Windows"> In **This PC**, choose **Map network drive**, paste the URL as the folder, and pick **Connect using different credentials**. Windows caps WebDAV transfers at 50 MB per file by default — raise `FileSizeLimitInBytes` under the `WebClient\Parameters` registry key and restart the WebClient service. On a non-standard HTTPS port, set `BasicAuthLevel` to `2` under the same key. </Tab> <Tab title="iOS Files"> Tap the three-dot menu, choose **Connect to Server**, and enter the same URL and credentials. Files supports browsing and downloading; in-place editing works for formats with an iOS app. </Tab> <Tab title="rclone"> ```bash rclone config create tale webdav \ url=https://<your-site>/dav/<orgSlug>/documents/ \ vendor=other \ user=<your-email> \ pass=$(rclone obscure '<app-password>') rclone copy ./local-folder tale: --progress ``` `vendor=other` is correct — Tale's server is generic, not a named flavour rclone recognises. </Tab> </Tabs> ## What the mount can do Reads and writes mirror your Document Hub permissions, files you upload index and search like direct uploads, and their source field is set to `webdav` for filtering in audit views. Project files are the exception: a project's **Knowledge** tab is scoped to that one project and never appears over WebDAV, so the mount shows only the org-wide Document Hub. The `.trash/` namespace lists soft-deleted documents read-only — download for recovery, restore through the UI. Editors that take WebDAV locks (Office, LibreOffice) get them; a competing write during an edit returns `423 Locked`. ## Revoking Revoke a password with the trash icon on its row — the next request with it is rejected, other devices are untouched, and any locks it held are released. There is no undo; mint a new password if you revoke the wrong row. <Warning> Basic auth sends the app-password on every request. Mount only over HTTPS, keep the password in the OS keychain, and never paste it into a `https://user:pass@host/` URL — shell history and proxy logs outlive the mount. Revoke immediately on any suspected leak. </Warning> ## Where this fits WebDAV is the per-user, device-facing door to the same data as the [Document Hub](/platform/knowledge/documents); the wire protocol lives under [WebDAV API](/develop/webdav-api). For machine-to-machine imports, [API keys](/platform/admin/api-keys) plus the REST API are usually the better fit. # Crawling Source: https://tale.dev/docs/platform/knowledge/crawling A Website is the knowledge base's shape for "a public site the agent should know about". You hand Tale a domain and a scan interval; the crawler discovers URLs, fetches pages, extracts the main content, chunks and embeds the text, and serves the chunks back at reply time the same way it does for Documents. This page walks what you see between adding a domain and agents citing its pages. <Frame caption="Adding a website — domain plus scan interval is the whole form."> ![The Add website dialog on the Websites tab, asking for a domain and a scan interval that defaults to every six hours.](/images/platform/websites-add-dialog.webp) </Frame> ## Adding a website Open **Knowledge > Websites** and click **Add website**. The dialog has two fields: **Domain** (for example `example.com`) and **Scan interval** — every 1 hour, 6 hours (the default), 12 hours, 1 day, 5 days, 7 days, or 30 days. Tale normalises the domain — `https://`, `www.`, and trailing slashes are tolerated — and rejects anything that does not parse as a hostname. Click **Save**; the scheduler picks new websites up on its next tick, so the first scan starts within seconds. <Note> There is no auth field and no include/exclude path list — the crawler sees exactly what an anonymous visitor sees. Anything behind a login belongs in [Documents](/platform/knowledge/documents) or an [integration](/platform/integrations/overview) instead. </Note> ## How URLs are discovered The crawler tries the cooperative path first. It resolves the homepage and walks every sitemap the site publishes — `sitemap.xml`, sitemap indexes, gzipped and robots-declared sitemaps — collecting the URL list the site itself maintains. Sites with a healthy sitemap get complete coverage with no guessing. When the sitemap is missing, broken, or empty, the crawler falls back to a breadth-first link walk from the homepage: in-domain links only, external and social links dropped, navigation and footer chrome stripped before extraction. The fallback covers sitemap-less sites, but it cannot match a well-maintained sitemap for completeness. ## The scan schedule The interval decides how often URLs are re-discovered and pages re-fetched. Each scan is incremental: unchanged pages are skipped, changed pages are re-extracted and re-embedded, new pages are added, removed pages are dropped from the index. Agents pointed at the website see the new content on the next retrieval — there is no separate publish step. ## Reading the table Each row shows the domain, its **Status** — **Idle** between scans, **Scanning** in flight, **Active** after a successful scan, **Error** when the last scan failed, **Deleting** during removal — the **Indexed** percentage (hover for crawled-of-total page counts), the last **Scanned** time, and the **Interval**. Open a row for the site's discovered title and description; click **View pages** for the page list — every indexed URL with its word count, chunk count, and last-crawled time, plus a search box that runs over the indexed chunks, which is the quickest way to check what an agent would actually retrieve. ## Where this fits Crawling is the cheap way to bring a public site into agent context: a domain, a cadence, and the rest is the crawler's problem. The trade-off is the anonymous-visitor boundary — private content needs [Documents](/platform/knowledge/documents) or an integration. For how the Website rows sit beside Customers, Products, and Vendors, read [Structured data](/platform/knowledge/structured-data). # Documents Source: https://tale.dev/docs/platform/knowledge/documents The Documents tab is the knowledge base's file surface. Editors upload files, Tale runs each one through the indexing pipeline — extract the text, chunk it, embed the chunks, store them — and agents whose knowledge scope covers the document retrieve relevant passages at reply time and cite them. This page covers the operator side: uploading, the status column, team scoping, folders, and the document lifecycle. <Frame caption="The Documents table — size, source, RAG status, and team scope per file."> ![The Knowledge area's Documents tab listing three uploaded text files with size, source, RAG status, and team columns.](/images/get-started/documents-list.webp) </Frame> ## Uploading Open **Knowledge > Documents** and click **Upload documents** — the menu offers **From your device** and **From Microsoft 365**. The upload gate accepts the formats that cover the bulk of org knowledge: PDF, Word (`.doc`, `.docx`), OpenDocument text (`.odt`), PowerPoint (`.ppt`, `.pptx`), Excel (`.xls`, `.xlsx`), CSV, plain text, and images (JPG, PNG, GIF, WEBP). Anything else is refused at upload. Uploading and indexing are separate facts, and the **RAG status** column tracks the second one: **Indexing** while the pipeline runs, **Indexed** when agents can retrieve the content, **Failed** when the pipeline errored, and **Needs reindex** when the stored chunks are stale. Modern formats index; the legacy Office trio (`.doc`, `.xls`, `.ppt`) uploads and stays downloadable but shows **Not indexed** — agents cannot retrieve its content until you re-save it in the modern format. ## Importing from Microsoft 365 **From Microsoft 365** imports from OneDrive or SharePoint instead of disk: pick files or folders, then choose the import mode. **One-time import** brings the files in once — they behave like uploads from disk. **Sync import** keeps the selection synchronized: new files in the OneDrive folder appear on a later sync pass, changed files re-index, and files deleted at the source leave the workspace. Both modes preserve the folder structure of your selection. Sync covers personal OneDrive folders — a SharePoint selection always imports once. To stop syncing — a whole synced folder or a single synced file — open the row's menu and click **Stop syncing**; the imported documents stay in the workspace and stop updating. Deleting a synced folder or file also stops its sync. In every case the originals in OneDrive are untouched. ## Scoping, folders, sources Each row carries a **Teams** cell — **Organization-wide** by default, or the teams you pick via **Assign team** in the row menu. A team-scoped document is invisible to members and agents outside the team; this is the knowledge base's access lever. Project files are outside this model entirely: a project's **Knowledge** tab holds files scoped to that one project, and they never appear in this library or in its team scoping — see [Manage files](/platform/projects/manage-files). **New folder** keeps large libraries navigable, and integrations bring their own structure: documents synced from OneDrive or SharePoint land under sync folders and show their origin in the **Source** column, which keeps citations traceable to the upstream system. <Warning> Deleting a folder permanently deletes every file and subfolder inside it. Deleting a OneDrive sync folder also removes its auto-sync configuration and history — though never the files in OneDrive itself. </Warning> ## Reindex and delete **Reindex** (row menu) re-runs the pipeline on the stored file — the right move after an indexing failure or when a document shows **Needs reindex**. **Delete** removes the document and its indexed chunks; the confirmation says it plainly — the action cannot be undone. Re-uploading the same file brings the content back as a fresh document. Clicking a document opens the preview, with a sidebar showing size, source, RAG status, teams, uploader, and modification date — the fastest way to check what a citation actually points at. ## Documents versus structured data Documents are the unstructured half of the knowledge base. When the content is a list of things with the same fields — customers, products, suppliers — a typed record serves agents better than a spreadsheet upload: exact values instead of retrieved passages. The decision rules live in [Structured data](/platform/knowledge/structured-data). ## Where this fits Documents are the most-used corner of the knowledge base — most citations in most replies point here. The retrieval side — how an agent's knowledge scope decides what it searches — is [Agent knowledge](/platform/agents/knowledge); the fact-sized sibling surface is [Knowledge entries](/platform/knowledge/knowledge-entries), which rides this same pipeline one document at a time. # Knowledge entries Source: https://tale.dev/docs/platform/knowledge/knowledge-entries Knowledge entries are the knowledge base's fact surface. Where a document carries a whole file, an entry carries one small, durable fact — "the store opens at 9", "the return window is 3 days" — keyed by a topic name. Entries ride the same indexing pipeline as documents, so every agent whose scope covers them retrieves and cites them like any other source; what makes them special is how they get in and how corrections replace what they correct. <Frame caption="The Knowledge entries tab — topic, content, source, and indexing status per fact."> ![The Knowledge entries tab listing three manually added facts, each showing a Manual source tag and an Indexed status badge.](/images/platform/knowledge-entries-list.webp) </Frame> ## Where entries come from **From chat, with your approval.** Agents with the knowledge-write tool enabled can propose saving a fact you stated or corrected during a chat. The proposal appears as a card in the chat — **Save to knowledge base**, with the topic and the full content; when the topic already exists the card becomes **Update knowledge base** and warns that approving will replace the existing entry. Nothing lands until you click **Approve**; **Reject** discards it. <Note> The tool is off by default — enable it per agent in the agent's tool settings. An agent can never write into the org's shared knowledge without a human signing off on the exact text. </Note> **Manually.** Click **Add entry** on **Knowledge > Knowledge entries**. Give it a **Topic** (up to 120 characters — short and stable, like a heading) and the **Content** as markdown (up to 8000 characters), written so it makes sense without any surrounding conversation. The **Source** column keeps the two origins apart: **Chat** or **Manual**. ## One live version per topic Topics are the dedup key: an approved chat proposal for an existing topic, or an edit, replaces the live version rather than adding a second one — the knowledge base never serves two versions of the same fact. Adding a new entry under an existing topic is refused with a duplicate-topic error; edit the existing entry instead. Replaced versions are not lost. Open an entry to see its details — indexing status, last update, and the **Version history** with every superseded version and when it was replaced. Only the live version is indexed for retrieval; the history exists for audit and reference. ## Editing, indexing, deleting Editing creates a new live version and re-indexes in the background — the **Status** badge dips to indexing and returns to **Indexed** when search picks up the new text. Deleting removes the whole entry: the confirmation warns that it also disappears from the knowledge base, so agents can no longer find it, and that the action cannot be undone. If the fact was right, add it again. ## Where this fits Knowledge entries close the loop between conversations and the knowledge base: a correction made once in chat becomes a fact every agent retrieves, with a human approving the exact wording and one live version per topic guaranteeing the old fact disappears when the new one lands. For the file-shaped half read [Documents](/platform/knowledge/documents); for how agents bind and retrieve, read [Agent knowledge](/platform/agents/knowledge). # Knowledge Source: https://tale.dev/docs/platform/knowledge/overview Knowledge is the area where the org's data lives so agents can read and cite it. Editors curate it once; agents retrieve over it at reply time, which is why an agent in Tale can answer with your reality instead of the model's training data. The area opens on six tabs: **Documents**, **Knowledge entries**, **Websites**, **Products**, **Customers**, and **Vendors**. <Frame caption="The Documents tab — the most-used corner of the knowledge base."> ![The Knowledge area's Documents tab listing three uploaded text files with size, source, RAG status, and team columns.](/images/get-started/documents-list.webp) </Frame> ## The two shapes Everything in the area is one of two shapes. **Indexed content** — the files in Documents, the facts in Knowledge entries, the pages a website crawl brings in — runs through the indexing pipeline (extract, chunk, embed, store) so agents retrieve relevant passages and cite them. **Typed records** — Products, Customers, Vendors — are rows with named fields that agents read as data, not prose: exact values, no retrieval guesswork. The shape you pick decides how an agent can use the content, which is why [Structured data](/platform/knowledge/structured-data) is a decision page, not just a reference. ## How agents reach in An agent does not see the whole library by default. The agent's **Knowledge** tab controls its retrieval scope — which parts of the library it searches at reply time — and team-scoped items stay invisible to agents and members outside the team. Retrieval is driven by the agent's RAG-tagged tools, and every retrieved passage carries its source, so citations point back at the file, entry, or page it came from. The agent-side mechanics live in [Agent knowledge](/platform/agents/knowledge). ## Pages in this section <CardGroup cols="2"> <Card title="Documents" icon="file-text" href="/platform/knowledge/documents"> Uploading files, the indexing pipeline, supported formats, and the per-document lifecycle. </Card> <Card title="Knowledge entries" icon="book-open" href="/platform/knowledge/knowledge-entries"> Small, topic-keyed facts — captured from chat with approval or added by hand. </Card> <Card title="Crawling" icon="globe" href="/platform/knowledge/crawling"> Turning a public website into knowledge — domain, scan interval, and the indexed-pages view. </Card> <Card title="Structured data" icon="table" href="/platform/knowledge/structured-data"> Customers, Products, Vendors, Websites — when a typed record beats a document. </Card> </CardGroup> ## Where this fits Knowledge is the data layer every grounded reply stands on; without it, agents only know what the model already knows. Bring content in through the tab that matches its shape, then wire agents to it — the natural next read is [Documents](/platform/knowledge/documents) for files, [Structured data](/platform/knowledge/structured-data) for records, and [Agent knowledge](/platform/agents/knowledge) for the retrieval side. # Structured data Source: https://tale.dev/docs/platform/knowledge/structured-data Tale's knowledge base ships two shapes side by side. Documents are text the agent retrieves chunks from; structured records are typed rows the agent reads fields from. The shape you pick is the most important decision in how an agent will use your knowledge — get it wrong and the agent either dilutes a clear answer or guesses at a value you have on file. This page hands you the mental model for when each shape is the right one. Read it before you load a folder of files; come back to it when you are tempted to upload a spreadsheet as a PDF. ## Documents versus structured records A document is free-form: the indexing pipeline extracts text, chunks it, embeds the chunks, and serves passages via retrieval at reply time. The agent sees passages and cites them by source. This is the right shape when the content is prose — contracts, manuals, knowledge-base articles, meeting notes. A structured record is typed: the entity has known fields (a customer has a name, an email, an industry; a product has a SKU, a price, stock). The agent reads the fields directly, joins across entities, and answers with the value. This is the right shape when the source is a database row — accounts, orders, parts, supplier records. ## The four built-in entities Four structured tabs sit beside **Documents** and **Knowledge entries** in the Knowledge area: - **Customers** — the people and organisations you do business with. - **Products** — the things you sell. - **Vendors** — the suppliers you buy from. - **Websites** — public sites a crawler fetches on a schedule; the record holds the domain and scan settings, the indexed pages hold the content ([Crawling](/platform/knowledge/crawling)). Structured records share the knowledge base's team-scoping levers: a team-scoped record is invisible outside the team the same way a team-scoped document is. ## Content models for custom shapes When the four built-ins do not fit, content models let you define a custom structured record type: name the entity, declare its fields, set field-level access, and the new type appears alongside the built-ins. The definitions live under [governance content models](/platform/admin/governance/content-models). <Note> Content models cost governance attention — every field's access and retention policy is yours to set. Reach for them when the data is genuinely a new shape, not a slight variation on one of the four built-ins. </Note> ## Putting it together — a CRM agent A CRM agent that answers "where are we with Acme?" uses both shapes. The Customers entity holds the canonical record — name, primary contact, industry, status. Documents hold the call notes and contracts. The agent reads the customer's fields directly, retrieves passages from the documents, and answers with both: the structured status from Customers, the latest context from the most recent call note. Without structured records, the agent has to find Acme by name across PDFs and risks confusing two customers with similar names. Without documents, the agent knows Acme's status but cannot tell you what happened on Tuesday's call. ## When to reach for it | Use … when | Documents | Structured record | | ---------------------------------------------------------- | --------- | ----------------- | | The source is free prose | ✓ | | | The source has typed fields and you want exact values back | | ✓ | | You need to join across many records | | ✓ | | The agent should cite passages by location | ✓ | | ## Where this fits Structured data is the seam between your operational data and the agent surface. Use the four built-ins for what they cover; reach for [content models](/platform/admin/governance/content-models) when a fifth shape appears. The next read worth queuing is [Documents](/platform/knowledge/documents) — the indexing pipeline that serves the unstructured half. # Environment variables & secrets Source: https://tale.dev/docs/platform/member/environment Environment variables & secrets is your personal store of variables that Tale injects into every agent sandbox you run in this organisation. When an external agent starts its sandbox, each entry you have saved here is set in the container's environment before the agent runs, so a command the agent issues — or the agent itself — can read it. The headline use is credentials: a [bring-your-own external agent](/platform/agents/external-agent) authenticates with the API key or token you keep here instead of the platform gateway. It is a member-level page that every role can reach, and the entries are scoped to you and to the current organisation, so they never leak to teammates and never follow you into another org. This page covers the two kinds of entry, how secrets are protected, the rules a name and value have to satisfy, and where the values end up. <Frame caption="Settings > Environment — the saved entries, each with the Secret switch that decides whether its value can be read back."> ![The Environment settings page listing three saved entries — ANALYTICS_ORG and CRM_BASE_URL with their values in plain sight, and CRM_API_TOKEN masked as dots with its Secret box ticked — above an Add variable action.](/images/platform/settings-environment.webp) </Frame> ## Variables and secrets Open **Settings > Environment**. **Add variable** opens a dialog for a new entry, with the list of what you have saved below. Each entry is a **Name** and a **Value**, plus a **Secret** switch that decides how the value is stored and shown. A plain variable is stored as-is and shown back in full in the list — use it for non-sensitive configuration the agent expects, a region name or an endpoint. A **secret** is encrypted the moment you save it and is write-only from then on: the list shows `••••••••` in place of the value, and there is no way to read it back. Turn the switch on for anything sensitive — an API key, an OAuth token, a password. The trade-off is that you cannot review a secret's value later, so if you are unsure it is right, delete it and add it again rather than hunting for a reveal button that does not exist. Each row carries the name, the value or its mask, and when it was last updated. The trash icon asks for confirmation before it removes the entry, because deleting one takes it out of every sandbox of yours on the next run. ## Names, values, and limits A **name** must start with a letter or underscore and contain only letters, numbers, and underscores — the shape of an ordinary environment variable, `MY_API_KEY` rather than `my-api.key`. Names are capped at 128 characters and values at 8,192, which is room for a long token or a multi-line key but not a file. You can keep up to 100 entries. Tale trims spaces from the start and end of a value when you save it, because a stray newline from a copy-paste is the most common reason a token silently fails. It does not trim spaces or line breaks _inside_ the value, but it warns you when it finds them: a credential normally has none, so interior whitespace usually means a token wrapped across lines in your terminal when you pasted it. The warning does not block the save — a genuinely multi-line secret such as a PEM private key keeps its line breaks — so read it and decide. ## How the values reach the sandbox A secret never travels in the clear except into your own sandbox. At rest it is encrypted in Tale's backend under a key the platform holds, and the list query returns only the mask, never the plaintext. When a turn starts, the platform decrypts your secrets and sets them, alongside your plain variables, in the environment of your sandbox for that run. Whenever a secret is injected for a turn, that access is recorded in the audit log. That last step is the boundary worth understanding: the values land inside your sandbox container, so the isolation of the sandbox — not the secret store — is what stands between your credentials and anything else that runs there. This matches how the in-sandbox GitHub token works, and it is why these entries are scoped to you alone rather than shared with the org. It is also what makes a [bring-your-own agent](/platform/agents/external-agent) possible at all: the provider credential it uses to reach its model is one of these secrets. ## Where this fits Environment variables & secrets is the one member-level page that reaches into the sandbox rather than the chat — it is how your own keys and configuration get to the agents you run, without an Editor or Admin setting them for you. The entry you will add most often is the provider credential for a [bring-your-own external agent](/platform/agents/external-agent); read this page alongside that one to see both halves — where the credential is stored and how an agent is told to use it instead of the platform gateway. For the rest of your personal settings — display name, password, custom instructions — see [Preferences](/platform/member/preferences). # Install as app Source: https://tale.dev/docs/platform/member/install-as-app Tale ships as a Progressive Web App. Installing it puts an icon on your dock or home screen, runs Tale in its own window without browser chrome, and keeps the same session you had in the browser. There is no separate native build to download and no extension to install — the same URL you sign in with is the same app, in a standalone shell. This page covers the three places you trigger the install: the **Get app** row in your profile menu on Chromium browsers, the share-sheet step on iOS Safari, and the install banner Android Chrome surfaces on its own. Once installed, Tale behaves identically; the install only changes the chrome around it. ## The profile-menu shortcut On Chrome, Edge, Brave, Arc, and the other Chromium browsers, Tale's profile dropdown carries a **Get app** row when the browser is willing to install. Open the menu from your avatar in the top-right, scroll past the theme switcher and the language switcher, and click **Get app**. The browser opens its native install confirmation; accept it, and Tale lands in your dock (macOS), your taskbar (Windows), or your apps list (ChromeOS) within a second or two. The row is only there when the browser fired its `beforeinstallprompt` event and the app is not already installed. Browsers that do not fire that event — Firefox, Safari, anything in a private window — do not show the row, so the menu stays one item shorter rather than asking for something it cannot deliver. ## iOS and iPadOS iOS Safari does not fire `beforeinstallprompt`, so the **Get app** row does not appear in the menu. The install path lives in Safari's share sheet instead. Open Tale in Safari, tap the share icon in the toolbar, scroll down to **Add to Home Screen**, and confirm. Tale appears on your home screen with the same icon as the browser favicon. Tap it, and Tale opens in its own window — no Safari address bar, no tab strip, no back button beyond what Tale itself surfaces. Notifications work the same way they do in the browser tab; the install is the only difference. Other iOS browsers — Chrome, Edge, Firefox on iOS — are Safari under the hood. They do not have an Add-to-Home-Screen entry of their own. The Safari path is the only iOS install path that produces a real standalone app. ## Android Android Chrome handles installation in two places. The first is the same **Get app** row in Tale's profile menu, identical to the desktop flow. The second is Chrome's own install banner — a one-line bar that slides up from the bottom of the page on sites it considers installable. Tap **Install** on the banner, confirm in the system sheet, and Tale lands on your home screen. If you dismissed the banner once, it usually does not come back for a while. The profile-menu shortcut keeps working whether or not the banner has been shown. Other Android browsers — Firefox, Samsung Internet, Brave — each have their own install path under their browser menu, typically labelled **Install app** or **Add to Home Screen**. ## After installing Tale running in a PWA window is the same Tale running in a browser tab. The session, the chats, the knowledge base, the agents — all of it is the same surface. The differences are cosmetic and small: no browser chrome around the app window, an icon in your launcher, and on most platforms the window remembers its size and position between launches. Uninstalling follows the platform convention. On macOS, drag the icon out of the dock; on Windows, right-click and uninstall; on iOS and Android, long-press the icon and remove. Uninstalling clears the PWA shell but not the session — sign back in through the browser, and your data is where you left it. ## When to reach for it The install is worth it once you find yourself opening Tale every day and want it to feel like one of your apps rather than one of your tabs. It is also the right move when you want the chat window pinned to a virtual desktop or a stage-manager slot that browser tabs would not respect. Skip the install if you sign in from many machines and prefer the browser tab — Tale works the same way either way. The neighbouring read is [Member overview](/platform/member/overview) — it is the map of what the rest of the Member surface covers once Tale is sitting in your dock. # Member Source: https://tale.dev/docs/platform/member/overview Member is the default role most people in most orgs carry. It is the end-user surface of Tale — chat with agents, browse the knowledge base, reply to customer email in an installed automation's Inbox, act on the approvals others have routed to you, and leave feedback on replies. Members do not build agents, do not configure providers, do not install automations. They use the product the Editors and Developers built for them. This overview names what a Member can do and points at the per-feature pages. Members typically land on Chat first; the rest of this page is what to read once chat alone is not enough — when you want to know where a citation came from, what an approval card is, or what a project bundles. ## What Member covers The Member surface is intentionally narrow. The four buckets are: - **Chat** — pick an agent (or none), send a message, read the reply. The composer surfaces the prompt library, attachments, voice mode, arena mode for side-by-side comparison, and the Canvas pane when a reply produces more than the chat can hold inline. - **Knowledge** — browse documents, customers, products, vendors, websites the org has loaded. Read-only for Members; the curating happens on the Editor side. - **Inbox** — reply in the **Inbox** tab an installed email automation adds. Members answer when an agent hands a conversation back; installing the automation itself is an admin action. - **Approvals** — read the approval cards routed to you. Click Approve, Reject, or Request changes; leave a comment if the rule asks for one. The org configuration settings — providers, integrations, agents, governance — are hidden for Members; the work surface is the bulk of what is left. The exception is a small personal settings group every role carries: Account, Personalization, and [Environment variables & secrets](/platform/member/environment), the keys and variables injected into the sandboxes you run. ## Pages in this section This section is short — the Member surface is the cross-section of pages that Editors build for and that everyone uses. The deeper reading lives in the per-feature areas. <CardGroup cols="2"> <Card title="Chat" icon="message-circle" href="/platform/chat/overview"> The everyday entry point — composer, agents, attachments, citations. </Card> <Card title="Knowledge" icon="library" href="/platform/knowledge/overview"> The read-only window into what the org has loaded. </Card> <Card title="Built-in automations" icon="inbox" href="/platform/automations/builtin"> The email automations that add an Inbox tab — and what each one does. </Card> <Card title="Approvals" icon="check-check" href="/platform/approvals/concepts"> What an approval card is and what each button does. </Card> </CardGroup> ## Where this fits Member is the role that consumes what the Editor builds and the Admin governs. The natural first read is [Chat](/platform/chat/overview) — it is where every Member spends most of their time, and most of the other Member surfaces fan out from a chat that wanted to do something more. # Preferences Source: https://tale.dev/docs/platform/member/preferences Preferences are the dials that belong to you rather than to the org. Your name is what agents and teammates see in chats and approvals. Your locale and theme follow you between devices. Your custom instructions and memories shape how agents reply to you specifically — separately from anything the Admin or Editor has set at the org level. This page maps where each lever lives and what it changes. The shape is intentionally two-layered: the profile menu (everywhere, one click from the avatar) carries the quick toggles; **Settings > Account** and **Settings > Personalization** carry the deeper account fields. Everything here is yours — none of it leaks to other members or other orgs. ## The profile menu Click your avatar in the top-right. The dropdown opens with your name, your email, and the current build version. Below the header sit four quick controls every member sees regardless of role: the **theme** switcher (System / Light / Dark), the **language** sub-menu (English, Deutsch, Français), the **Get app** row when the browser can install Tale as a PWA, and **Log out**. Theme and language take effect immediately and persist per-device. The menu also carries an organisation switcher when you belong to more than one org and a team filter when your current org has teams. Those are not preferences — they change what Tale shows you, not how Tale behaves. Below the team filter, **User settings** opens **Settings > Account**, the page covered next. ## Account — name, email, password, two-factor Open **Settings > Account**. Three sections sit on the page: **Profile**, **Security**, and **Two-factor authentication**. The Profile section shows your **email** first, then your **name** — the email implies the name Tale suggests, which you can edit freely. The name is editable inline; the change saves and propagates to every chat and approval the next time they render. Email is read-only — it is what you signed in with, and changing it goes through support. There is no avatar field on the page; Tale derives an avatar from your name's initials. The Security section holds a single button: **Change password** if you signed up with email and password, **Set password** if your account is federated through SSO and you want to add a password as a fallback. Both flows enforce the org's password policy and surface the rules live as you type, and a wrong current password is flagged inline on the field rather than as a transient error. Changing your password signs you out of every device — the dialog warns you before you confirm, and you'll sign back in with the new password. The Two-factor section pairs the account with a TOTP app or a hardware key and shows the backup codes once at enrolment. ## Personalization — custom instructions, memories, voice output Open **Settings > Personalization**. The page gates each feature with an on/off toggle that follows the org default until you override it. <Frame caption="Settings > Personalization — the per-feature toggles above the custom instructions field, the memories list, and the voice-output picker."> ![The Personalization settings page, showing on/off toggles for custom instructions, memories, and voice output, with the custom instructions text field and saved memories list below.](/images/platform/settings-preferences.webp) </Frame> **Custom instructions** is a free-form text field — up to 4,000 characters — that every agent receives as additional context for your conversations specifically. Use it for the things you would otherwise say at the top of every chat: your role, your preferred reply style, the projects you are working on, the constraints the agent should respect. The org default decides whether the feature is on for new members; your toggle overrides it for your own account. **Memories** are short facts the agent saves about you between chats — a topic you asked about, a preference you stated, a context you would not want to repeat. Saved memories appear in a list with a delete button on each row; pending memories surface in their own section with **Approve** and **Dismiss** controls so nothing lands in your record without you seeing it. Toggle the feature off and existing memories stop being used until you turn it back on. **Voice output** picks the voice an agent uses when it speaks in voice mode. The setting only applies when the org has a voice provider configured; otherwise the section explains the gap and points at the Admin. ## Signing out The **Log out** row at the bottom of the profile menu confirms with a dialog before clearing the session. After confirming, Tale does a full page reload to the sign-in page so no stale state lingers in the tab. Sign-out is per-device — signing out on your laptop does not log you out on your phone, and vice versa. ## Where this fits Preferences are the line between you and the rest of the org. The org Admin sets defaults — including whether personalization is on for new members, what the password policy is, which models are allowed — and your preferences override the defaults where Tale lets them. One personal page sits apart from this set: [Environment variables & secrets](/platform/member/environment) holds variables and credentials scoped to you within a single organisation rather than following you across them — the place to keep the provider key a bring-your-own agent uses. The next read worth queuing is [Member overview](/platform/member/overview) for the map of the rest of the Member surface, or [Install as app](/platform/member/install-as-app) if you want Tale to live in your dock rather than your browser tabs. # Model catalog Source: https://tale.dev/docs/platform/models Every model picker in Tale — the composer's model menu, an agent's model binding, the defaults the crawler and RAG services use — draws from one catalog: the models declared on your organisation's AI providers. A fresh instance ships with a single provider, **OpenRouter**, whose one key covers chat, vision, embeddings, transcription, text-to-speech, and image generation. This page is the reference for where that catalog lives in the UI, what the tags on each model mean, and what ships out of the box. <Frame caption="The provider drawer's model list — each model carries the capability tags that decide which pickers it appears in."> ![The provider details drawer under Settings > AI providers, showing a searchable model list where each row carries capability tags such as Chat and Image generation, with Fetch models, Sync from catalog, and Add model actions above it.](/images/platform/settings-provider-models.webp) </Frame> ## Where the catalog lives Open **Settings > AI providers** and click a provider row. The drawer lists everything the provider declares: its base URL and API key, its **Default Models**, and the **Models** list itself — searchable, with **Show more** past the first ten. **Add model** declares a new entry by hand; **Fetch models** pulls the list the provider's API reports. Models an admin marks as **Hidden from model pickers** stay resolvable for existing bindings but stop appearing in menus — that is how superseded versions retire without breaking old agents. Each model carries one or more capability tags: **Chat**, **Vision**, **Embedding**, **Transcription**, **Text-to-speech**, **Image generation**, **Image edit**. The tags are load-bearing — they decide which pickers a model shows up in and which platform capability is allowed to call it. A model with no matching tag never appears where that capability is needed. ## The shipped defaults The **Default Models** card names which model each background capability uses when nothing more specific is bound: | Capability | Shipped default | | ---------------- | ------------------ | | Chat | DeepSeek V4 Flash | | Vision | Qwen3 VL 32B | | Embedding | Qwen3 Embedding 8B | | Image generation | FLUX.2 [pro] | | Transcription | Whisper v1 | Text-to-speech for [voice mode](/platform/chat/voice-mode) ships on OpenAI's GPT-4o mini TTS through the same OpenRouter key, and [image generation](/platform/agents/image-generation) defaults to FLUX.2 [pro]. ## How the list stays fresh Models drift faster than docs. Two mechanisms on the **AI providers** page keep the catalog current: the **Model catalog** card refreshes model capabilities — pricing, context window, reasoning, vision — from OpenRouter's public catalog daily, and the **Weekly auto-sync of provider config** toggle merges newly released flagship versions into the org's provider config once a week, hiding superseded ones and leaving any field you customised untouched. The shipped list below is regenerated from the same source, so it matches what a fresh instance sees: <!-- MODELS_TABLE:START --> <!-- Auto-generated from builtin-configs/providers/openrouter.json by the weekly model-catalog sync. Do not edit by hand. --> | Provider | Model | Capabilities | Context | Input ($/M) | Output ($/M) | | ----------------- | ------------------------------------ | ---------------------------- | ------- | ----------- | ------------ | | AI21 | Jamba Large 1.7 | chat | 256K | 2.00 | 8.00 | | Amazon | Nova Premier | chat, vision | 1M | 2.50 | 12.50 | | Amazon | Nova 2 Lite | chat, vision | 1M | 0.30 | 2.50 | | Anthropic | Claude Fable (latest) | chat, vision | 1M | 10.00 | 50.00 | | Anthropic | Claude Fable 5 | chat, vision | 1M | 10.00 | 50.00 | | Anthropic | Claude Sonnet 4.6 | chat, vision | 1M | 3.00 | 15.00 | | Anthropic | Claude Haiku 4.5 | chat | 200K | 1.00 | 5.00 | | Anthropic | Claude Opus 4.8 | chat, vision | 1M | 5.00 | 25.00 | | Black Forest Labs | FLUX.2 [flex] | image-generation, image-edit | — | — | — | | Black Forest Labs | FLUX.2 [max] | image-generation, image-edit | — | — | — | | Black Forest Labs | FLUX.2 [pro] | image-generation, image-edit | — | — | — | | Cohere | Command A | chat | 256K | 2.50 | 10.00 | | Cohere | Command R | chat | 128K | 0.15 | 0.60 | | DeepSeek | DeepSeek V4 Pro | chat | 1M | 0.43 | 0.87 | | DeepSeek | DeepSeek V4 Flash | chat | 1M | 0.09 | 0.18 | | Google | Gemini 3 Pro | chat, vision | 1M | 2.00 | 12.00 | | Google | Gemini 3 Flash | chat, vision | 1M | 0.50 | 3.00 | | Google | Gemma 4 31B IT | chat, vision | 262K | 0.12 | 0.35 | | Google | Gemma 4 26B A4B IT | chat, vision | 262K | 0.06 | 0.33 | | Google | Nano Banana (Gemini 2.5 Flash Image) | image-generation, image-edit | 33K | 0.30 | 2.50 | | Liquid | LFM2 24B | chat | 128K | 0.03 | 0.12 | | Meta | LLaMA 4 Maverick | chat | 1M | 0.15 | 0.60 | | Meta | LLaMA 4 Scout | chat | 10M | 0.10 | 0.30 | | Microsoft | Phi-4 | chat | 16K | 0.07 | 0.14 | | MiniMax | MiniMax M3 | chat, vision | 1M | 0.30 | 1.20 | | Mistral | Mistral Large 3 | chat | 262K | 0.50 | 1.50 | | Mistral | Mistral Medium 3.5 | chat, vision | 262K | 1.50 | 7.50 | | Moonshot AI | Kimi K2.6 | chat, vision | 262K | 0.68 | 3.41 | | Moonshot AI | Kimi K2.7 Code | chat, vision | 262K | 0.61 | 3.07 | | NVIDIA | Nemotron 3 Ultra | chat | 1M | 0.50 | 2.20 | | NVIDIA | Nemotron 3 Super | chat | 1M | 0.09 | 0.45 | | OpenAI | GPT-OSS 120B | chat | 131K | 0.04 | 0.18 | | OpenAI | GPT-4o mini TTS | text-to-speech | — | — | — | | OpenAI | GPT-5.3 Chat | chat, vision | 128K | 1.75 | 14.00 | | OpenAI | GPT-5.5 | chat, vision | 1M | 5.00 | 30.00 | | OpenAI | GPT-5.5 Pro | chat, vision | 1M | 30.00 | 180.00 | | OpenAI | Whisper v1 | transcription | — | — | — | | Perplexity | Sonar Pro | chat, vision | 200K | 3.00 | 15.00 | | Perplexity | Sonar | chat, vision | 127K | 1.00 | 1.00 | | Qwen | Qwen3.6 Max Preview | chat | 262K | 1.04 | 6.24 | | Qwen | Qwen3 Coder 480B | chat | 1M | 0.22 | 1.80 | | Qwen | Qwen3 VL 32B | chat, vision | 262K | 0.10 | 0.42 | | Qwen | Qwen3.6 Flash | chat, vision | 1M | 0.19 | 1.13 | | Qwen | Qwen3 Embedding 8B | embedding | — | 0.01 | 0.00 | | Qwen | Qwen3.7 Plus | chat, vision | 1M | 0.32 | 1.28 | | Reka | Reka Flash 3 | chat | 66K | 0.10 | 0.20 | | Xiaomi | MiMo V2.5 Pro | chat | 1M | 0.43 | 0.87 | | Z.AI | GLM 5.1 | chat | 203K | 0.98 | 3.08 | | Z.AI | GLM 5 Turbo | chat | 262K | 1.20 | 4.00 | | Z.AI | GLM 5V Turbo | chat, vision | 131K | 1.20 | 4.00 | | xAI | Grok 4.20 | chat, vision | 2M | 1.25 | 2.50 | <!-- MODELS_TABLE:END --> The full and live catalogue lives at [openrouter.ai/models](https://openrouter.ai/models); any model OpenRouter exposes can be added to your instance from the same drawer. ## Where this fits Models are the layer beneath every agent, every chat reply, every voice output, and every image the platform renders. OpenRouter is the default, not a requirement — adding a direct vendor, a local Ollama or vLLM server, or a second gateway is admin work covered in [Providers](/platform/admin/providers), and the file-based form of the same configuration lives under [Configuration → providers](/self-hosted/configuration/providers). For picking between chat models when more than one could do the job, [Arena Mode](/platform/chat/arena-mode) is the workflow built for exactly that question. # Project Backlog Source: https://tale.dev/docs/platform/projects/backlog A task at **`backlog` status** is proposed work nobody has committed to yet — most often synced in by an automation like [Triage GitHub issues](/platform/automations/builtin). It lives in the **leftmost lane** on the Board and the **top section** on the List, using the same card, detail sheet, status picker, and assignee picker as every other status. [Task automation](/platform/projects/task-automation) covers what happens once a task reaches **To do** and enters the assignment loop. ## A synced task Triage GitHub issues proposes one task per actionable open issue, keyed to the issue so a later sync never double-creates it: the title is `#<number> <title>` — for example `#482 Login button misaligned on Safari` — the description opens with the issue's own GitHub URL, and its labels mirror the issue's GitHub labels. A task you create from the board with the default status starts at **To do**; set **Backlog** in the create form when you want to file a proposal yourself. ## Moving work forward There are no backlog-only buttons. Drag a card to another lane, open the detail sheet and pick a new status, or assign an owner — the same paths you use for **To do** or **In progress**. Agent auto-assignment and assignment suggestions run only when a task is at **To do**, not while it sits in **Backlog**. If you move a proposal straight to **In progress** or assign it by hand, you are taking ownership yourself. Dismiss a proposal the same way you close any task: set status to **Cancelled** in the picker. A human cancellation sticks — a later GitHub sync does not resurrect a proposal you rejected while the issue stays open on GitHub. When an issue was **Done** on the board and someone reopens it on GitHub, sync moves the task back to **Backlog**. ## Where this fits Backlog is the intake column between an automation proposing work and your team committing to it. The natural next read is [Task automation](/platform/projects/task-automation) for what happens at **To do**, or [Built-in automations](/platform/automations/builtin) for what proposes tasks in the first place. # Project concepts Source: https://tale.dev/docs/platform/projects/concepts A project is the unit Tale reaches for when a body of work needs the same files, the same instructions, and the same working surfaces across many chats and many people. This page hands you the mental model — read it before you create your first project, and come back when you are deciding whether a growing chat should be promoted into one. <Frame caption="The General tab — identity, sharing, and the stats strip are the project's front door."> ![The General tab of the Website relaunch project showing the name and description fields, the sharing section with an Org-wide owning team, and a stats strip reading two files, no chats, and Org-wide.](/images/platform/project-general-tab.webp) </Frame> ## What a project owns **Chats** started inside the project carry its context automatically. They stay yours until you flip **Share with project** on a chat — the Chats tab splits into **Your chats** and **Shared with project** accordingly. Sharing a chat hides your personal memories and instructions from the responses other members see. **Instructions** are context that applies to every chat in the project — the framing, constraints, and vocabulary of the work — so nobody re-pastes them per chat. **Files** on the **Knowledge** tab are reference material every chat in the project can draw on, held in a folder tree you upload into once rather than re-attaching per chat. They stay scoped to this project — they never surface in the org-wide library or in `@` pickers outside it — see [Manage files](/platform/projects/manage-files). **Tasks and Discussions** make the project a place to run work, not just talk about it: a board with statuses and [automation](/platform/projects/task-automation), and [threaded discussions](/platform/projects/discussions) for decisions. **Agents & models** is a curation surface: which agents and models members see first — or see at all — inside this project ([Agents and models](/platform/projects/project-agents)). ## Creating and identity **Create project** asks for a name and a **Project key** — the prefix for task IDs like `WR-1`. The key is fixed; it cannot be changed after the project is created. Description, owning team, icon, and color are editable later on the **General** tab, where the unified **Save** and **Discard** buttons sit in the tab strip. ## Sharing model Sharing is by team, not by individual invitation. A project defaults to **Org-wide**; picking an owning team scopes it to that team, and additional teams can be added on the General tab. Org admins always have access. Renaming, archiving, and deleting live in the row menu on the projects list — deleting asks what happens to the content: detach the files and chats (they become library documents and personal chats) or delete them too. ## When to reach for it | Use … when | Project | Stand-alone chat | | --------------------------------------------- | ------- | ---------------- | | The same files apply across many chats | ✓ | | | The same instructions apply across many chats | ✓ | | | Multiple people work the same body of work | ✓ | | | The work has tasks, owners, and decisions | ✓ | | | The question is one-shot | | ✓ | A stand-alone chat is the right shape for exploring an answer once. The moment the context should outlive the chat, move it — the composer's **Move to project…** action carries an existing chat into a project. ## Where this fits Projects are the seam where chats, knowledge, and task automation meet. The natural next read is [Use projects](/tutorials/member/use-projects), which walks a fresh project end to end; the per-tab pages in this section go deeper on [files](/platform/projects/manage-files), [agents and models](/platform/projects/project-agents), and [discussions](/platform/projects/discussions). # Discussions Source: https://tale.dev/docs/platform/projects/discussions **Discussions** are threaded conversations that live with a project, beside its chats and tasks. Use them the way a team uses a discussion board: open a topic, talk it through, and resolve it — with the project's agents one @mention away. They reuse the chat message surface, so a discussion reads and composes like a chat, but it belongs to the project and every project member sees it, not just its author. <Frame caption="The Discussions tab — each row carries its category and lifecycle status."> ![The Discussions tab of the Website relaunch project listing two open discussions, one tagged Q&A and one tagged Decisions.](/images/platform/project-discussions-list.webp) </Frame> ## Opening a discussion Click **New discussion**, give it a **Title**, pick a **Category**, and write the opening message. The categories keep the board scannable: **General**, **Q&A**, **Ideas**, **Decisions**, **Announcements**, **Show and tell**, and **Polls**. Replies work like any message box — the placeholder says it: **Reply… use @ to mention a teammate or agent**. ## Humans first, agents on request Discussions are human-first. Your post is always saved as a message between people; an agent only responds when you bring one in. - **@mention an agent** in a message and that agent replies in the thread — the same routing and generation as chat, visible to everyone in the project. - With no @mention, nothing is summoned. A discussion can run its whole life without an agent ever speaking. This makes discussions the right surface for decisions that need a human record with occasional AI input — ask the agent for the data mid-thread, then decide around it. ## Lifecycle A discussion's category says what it is; its status says where it stands: - **Open** — active, the default. - **Resolved** — the question is answered or the decision is made. **Reopen** brings it back any time. - **Locked** — no further replies; the composer is disabled with a locked notice. **Unlock** reverses it. Resolving is bookkeeping, not archival — resolved discussions stay readable and searchable in the tab. ## Turning a discussion into work **Create task** spawns a task on the project's board from the discussion, linked back to the conversation it came from — a decision made in a discussion becomes trackable work without retyping it. The discussion remembers the conversion: it shows **Converted to task** with a **View task** link, and it can only be converted once. ## Where this fits Discussions fill the gap between a personal chat (one person and an agent) and the task board (work already decided): they are where a team decides. The tasks they spawn flow into [Task automation](/platform/projects/task-automation) like any other board task, and the @mention mechanics match [Agents in chat](/platform/chat/agents-in-chat). # Manage project files Source: https://tale.dev/docs/platform/projects/manage-files A project's **Knowledge** tab is the shared file area every chat inside the project can reach. Upload a file once and every chat in the project — and every agent that runs inside it — can read it without re-uploading. This page covers the folder tree, the upload mechanic, pinning, and the limits. The Knowledge tab is not the org-wide knowledge base in the [Documents](/platform/knowledge/documents) sense. Its files are scoped to one project and never appear in the org-wide library, in `@` pickers outside the project, or over WebDAV; deleting the project deletes the files. For org-wide reference material, use [Documents](/platform/knowledge/documents) and bind it to agents. <Frame caption="The Knowledge tab — the project's file tree, every file scoped to this project and indexed for retrieval."> ![The Knowledge tab of the Website relaunch project showing two indexed files in the file tree, a New folder button, and the Add file dropzone.](/images/platform/project-knowledge-files.webp) </Frame> ## Folders Project files live in a folder tree. **New folder** creates a folder at the root; the folder-with-plus icon on a folder row creates a subfolder inside it. Click a folder to select it — the drop area switches to _Add file to "…"_ and uploads land inside. Deleting a folder deletes everything in it, including the files' entries in the retrieval index; the confirmation says so before anything happens. Folders here are project-scoped: a same-named folder in the org-wide library is a different folder. ## A worked upload Open the project, click **Knowledge**, select the target folder (or none for the root), and drag files onto the drop area. The row appears in the tree and resolves to **Indexed** once retrieval has picked it up. The same upload is now reachable from any chat the project owns: send a message that references the topic and the agent retrieves it, or type `@` in the composer and pin the file — or a whole folder — to the turn. ## Replacing and deleting Replacing a file uploads a new copy under the same name; the earlier version moves to the project's version history. Citations from earlier chats keep pointing at the version that was active when the chat referenced it. Deleting a file removes it from the picker immediately; existing chats keep their citations, but the underlying file moves to [Trash](/platform/admin/governance/trash) with the rest of the project's retention cohort. ## Size limits Per-file and per-project limits are set by the org under [Policies and limits](/platform/admin/governance/policies-and-limits). Hitting a per-file limit fails the upload with a toast; hitting a per-project limit fails it with a different toast that names the policy. Members hitting a limit cannot raise it themselves — an Admin adjusts the policy, or the project owner deletes older files. ## Surfacing in chats A chat started inside a project automatically has access to every file in the project's Knowledge tab. The agent's retrieval tool sees project files alongside any agent-bound Knowledge sources. Citations from project files are scoped to the chat that produced them — sharing that chat outside the project preserves the citations, but the viewer cannot click through to the source unless they are also in the project. Pinning with `@` narrows a single turn: `@file` pins one file, `@folder` pins a folder and everything under it (the picker offers the project's folders inside project chats, and org-wide folders everywhere). Pinned files are also delivered to the agent's sandbox under `/user/uploads`, so coding agents — Claude Code and the other terminal agents included — can open the actual bytes, not just quote retrieval snippets. ## Where this fits Manage files is the operational page for the Knowledge tab — the conceptual framing is on [Project concepts](/platform/projects/concepts), and the agent-bound equivalent across the whole org is [Documents](/platform/knowledge/documents). If you find yourself re-uploading the same files into many projects, that is the signal to move them to Documents and bind an agent to them instead. # Projects Source: https://tale.dev/docs/platform/projects/overview A project is a shared workspace that bundles everything one piece of work needs — the chats, the reference files, the instructions, the task board, and the discussions — so the context follows the work instead of being re-pasted into every chat. Where a single chat answers one question, a project is where a team keeps a customer, a launch, or a long-running investigation moving. <Frame caption="A project's task board — one of the eight tabs every project carries."> ![A kanban task board inside the Website relaunch project, with seven task cards spread across the Backlog, To do, In progress, In review, Done, and Cancelled columns.](/images/platform/projects-task-board.webp) </Frame> ## The parts of a project Every project opens on the same tab strip: **General** (name, description, sharing, and recent chats), **Chats** (your chats in the project plus the ones shared with it), **Discussions** (threaded topics for the whole team), **Tasks** (the board, with a **Metrics** view), **Instructions** (context that applies to every chat in the project), **Knowledge** (the project's files, in a folder tree), **Agents & models** (which agents and models members see here), and **Secrets**. Apps installed into the project add their own tabs after these. ## Pages in this section <CardGroup cols="2"> <Card title="Project concepts" icon="compass" href="/platform/projects/concepts"> The mental model — what a project owns, when it beats a stand-alone chat, and how sharing works. </Card> <Card title="Manage files" icon="folder-open" href="/platform/projects/manage-files"> The Knowledge tab — uploading files into folders, index status, and how project files stay scoped to the project. </Card> <Card title="Agents and models" icon="bot" href="/platform/projects/project-agents"> Curating which agents and models appear in a project — Recommended versus Restricted. </Card> <Card title="Discussions" icon="messages-square" href="/platform/projects/discussions"> Threaded team conversations with categories, lifecycle, and agents one @mention away. </Card> <Card title="Task automation" icon="workflow" href="/platform/projects/task-automation"> Assigning board tasks to agents — the execution loop, the review gate, and the guardrails. </Card> <Card title="Backlog" icon="gauge" href="/platform/projects/backlog"> Proposed tasks an automation or teammate synced in — Start onto the board or Close them off. </Card> </CardGroup> ## Where this fits Projects sit beside Chat in the sidebar, and the handover is natural: a question starts in Chat, turns out to be bigger than one chat, and moves into a project — the composer's **Move to project…** action carries an existing chat across. If you are new to projects, start with [Project concepts](/platform/projects/concepts) for the model, then walk [Use projects](/tutorials/member/use-projects) end to end on a fresh one. # Agents and models in a project Source: https://tale.dev/docs/platform/projects/project-agents A project's **Agents & models** tab decides which agents and models members meet when they chat inside the project. It does not create new agents — agents are built org-wide under [Agents](/platform/agents/concepts) — it curates the existing catalog for this project's context, so a member opening the picker sees the right tools for the work first. <Frame caption="The Agents & models tab — one Recommended/Restricted choice for agents, one for models."> ![The Agents & models tab of a project showing two radio groups, Agents and Models, each offering a Recommended mode and a Restricted mode with an Add button.](/images/platform/project-agents-models.webp) </Frame> ## The two modes Agents and models are curated separately, each with the same two modes: - **Recommended** — the items you list are pinned to the top of the picker; everything else the member could normally use stays available below. This is the default, and the right mode for steering without blocking. - **Restricted** — only the items you list are available in this project. Members picking anything else get a clear refusal: the composer reports that the agent or model isn't available in this project and asks them to pick another. The list order is the order members see, and the first item is the default — drag to reorder. **Add agent** and **Add model** extend the list. <Warning> In **Restricted** mode an empty list locks every member out of chatting in the project — there is nothing left to pick. Add at least one item before saving, or switch back to **Recommended**. </Warning> ## What members experience Inside the project, the composer's agent picker and model picker reflect the curation — recommended items first, restricted items only. A chat moved into the project with a now-disallowed agent doesn't break silently: the send is refused with the agent-not-available message, and the member picks an allowed one. Outside the project nothing changes; curation is scoped to chats that run in the project's context. ## Who can change it Editing the tab follows org roles: an editor or admin role is required to save changes, and members without it see the project read-only, with a banner pointing them at a project editor. Changes land on **Save** in the tab strip — the same unified Save/Discard cluster the General and Instructions tabs use. ## When to reach for each mode | Use … when | Recommended | Restricted | | ----------------------------------------------------- | ----------- | ---------- | | You want the right agent to be the obvious first pick | ✓ | | | Members should keep access to the full catalog | ✓ | | | Compliance or cost demands a fixed, short list | | ✓ | | An expensive model must not be used for this work | | ✓ | ## Where this fits This tab is project-side curation of an org-side catalog: building agents, their instructions, and their knowledge is the [Agents](/platform/agents/concepts) section's job; deciding which of them this project surfaces is yours. For how the picker behaves inside a chat, see [Agents in chat](/platform/chat/agents-in-chat). # Task automation Source: https://tale.dev/docs/platform/projects/task-automation Assigning a board task to an AI agent puts it to work. The **task-ops pack** — eleven file-based workflows provisioned to every organization — covers the full lifecycle: triage, execution, review, escalation, SLA enforcement, and cleanup. Every workflow is a plain JSON file your organization owns: tune the thresholds, edit the prompts, or deactivate individual triggers on the workflow itself. A task an automation proposes sits in [Backlog](/platform/projects/backlog) until a human Starts it — from that moment on it's a board task like any other and enters the loop below. <Frame caption="The project task board — assigning a card to an agent is what starts the loop below."> ![A kanban task board inside the Website relaunch project, showing seven task cards spread across its status columns, from Backlog and To do through In review to Done and Cancelled.](/images/platform/projects-task-board.webp) </Frame> ## The execution loop 1. **Assign** a task to an agent (or let _unassigned triage_ score and route new tasks automatically — high-confidence matches auto-assign, the rest get a suggestion comment). 2. The agent **acknowledges** (task moves to _In progress_), works in its own task thread with the task tools, and posts its result as a comment. 3. The task parks at **_In review_** — agents can never set _Done_; that rule is enforced server-side regardless of any workflow configuration. 4. A human **approves** (the only automated path to _Done_) or **requests changes** with feedback, which re-engages the same agent on the shared thread and opens a fresh review gate. Reviews are answerable from the task sheet or directly from the Inbox. Failures roll the task back to _To do_ with an explanatory comment. When a decomposed root task has subtasks, the parent waits until the last subtask closes, then rolls up to _In review_. ## Mentions, dependencies, deadlines - **@-mention an agent** in a task comment or in the task description and it reads the mentioning text and acts. Typing `@` opens an autocomplete over members and the project's agents; the composer previews whether each mentioned agent will actually respond (automation off, budget exhausted, paused). Editing a description triggers only newly added mentions, and anything the automation writes itself never triggers anyone. - When a **blocker closes**, dependent tasks get a remaining-blocker note; fully unblocked agent work restarts automatically, human work gets an inbox notification. - **Due dates** drive an SLA ladder: a 24h warning, an overdue nudge, then a human escalation to the project creator and org admins — repeated once more if the task stays overdue. Each level fires at most once; pushing the due date out resets the ladder. ## Guardrails Every agent run — assignment, mention, revision, escalation, external — passes the same admission gate: - **Budgets** (per agent, monthly): at the warn threshold the agent gets an economy instruction and admins are notified once; at the pause threshold new runs are refused. Resets at month rollover. - **Concurrency caps** (per agent and org-wide): excess runs queue and start automatically when a slot frees. - **Per-task circuit breaker**: more than the configured runs per hour on one task pauses automation on that task until a human changes its status. Org-wide caps (run concurrency, per-task runs per hour) ship as fixed platform defaults; per-agent budget and parallelism live in the agent's configuration. ## Choosing an assignee Not every task belongs on a coding agent. Use this rule of thumb: | Task shape | Assign | | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Research, writing, summaries, personal deliverables | A **person** — disable unassigned triage on personal projects so agents do not auto-pick them up | | General automation with platform tools (comments, workflows, integrations) | An **Agent** (platform tool loop) | | Repository work — bugs, features, refactors, PRs | A **Coding agent** with the right dispatch: tale-daemon (`runtime`) for git workspaces, durable sandbox when configured, or accept that sandbox-only coding agents still run the platform loop on the board until you add those fields | The assignee picker groups **Agents** and **Coding agents** separately and shows a one-line dispatch hint for each coding agent. Image agents do not appear in the task assignee list. ## The kill switch The `task_automation` governance policy carries the master switch: switching it off stops the run path — in-flight work finishes, nothing new starts. It is admin-only and audited; on a self-hosted instance the policy is one of the org's governance config files, alongside the limits covered on [Policies and limits](/platform/admin/governance/policies-and-limits). ## Where this fits Task automation is what turns the project board from a to-do list into a delegation surface: a human assigns or approves, the pack runs everything in between, and the review gate keeps _Done_ a human decision. The natural next read is [Backlog](/platform/projects/backlog) for how proposed work enters the loop, and [The workflow editor](/platform/automations/editor) for tuning the pack's own workflows. # Prompt library Source: https://tale.dev/docs/platform/workspace/prompt-library The Prompt library is the saved-prompts surface of Tale. It is where you keep the chat starters you reach for more than once — a writing-voice prompt you reuse for every customer email draft, a debugging prompt your team passes around, a research prompt the whole org should agree on. Every role above Disabled can save and use prompts; the **visibility** lever on each prompt decides who else sees it. This page is the reference for what a prompt is, how the three visibility levels behave, how the version history works, and how prompts get into a chat. The library lives under **Prompts** in the sidebar; the same library surfaces inline in the chat composer. <Frame caption="The prompt library over the chat composer — provisioned starter prompts with the scope tabs and filters that narrow the list."> ![The prompt library dialog open over the chat composer, listing provisioned starter prompts with scope tabs and a filter row above them.](/images/platform/prompt-library-dialog.webp) </Frame> ## What a prompt is A prompt is a saved chunk of text — usually a question or an instruction you would otherwise type into the composer — with a title and a few metadata fields. When you reach for a saved prompt in chat, Tale pastes its content into the composer; you can edit before sending, the prompt is not a hidden system message. Each prompt carries: - A **title** (used in the picker; auto-generated from the content if you leave it blank). - The **content** (the actual prompt text). - A **visibility** — `Personal`, `Team`, or `Global`. - An optional **team** binding (when visibility is `Team`). - Optional **tags** for filtering. The library is searchable by title and content, filterable by visibility and tag, and sortable by recency. The composer's inline picker is the same library with the same filters. ## The three visibility levels **Personal** is your-eyes-only. A personal prompt appears in your own library and nowhere else; nobody in the org can see it. Reach for personal when the prompt is shaped to your own workflow and the rest of the team would not benefit. **Team** is shared with one team. Pick the team on save; every member of that team sees the prompt in their library. Reach for team when the prompt is shaped to a specific function — the support team's reply-tone prompt, the engineering team's bug-triage prompt — and the rest of the org would not benefit. **Global** is org-wide. Every member of the org sees the prompt in their library. Reach for global when the prompt encodes a decision the whole org should make the same way — the writing voice the brand expects, the question template every researcher should start from. Visibility is settable on save and editable later. Promoting a personal prompt to global takes one click and triggers no migration on the chats that already used it — old chats keep their pasted content, the new visibility affects only the library entry. ## Versioning Saving a prompt over an existing entry creates a new version. The version history is reachable from the prompt's row; each version records the editor, the timestamp, and the content diff. You can roll back to any prior version with one click. The version history is the place to look when a teammate edited a global prompt and the new content does not work for your use case. Roll back at the library level if everyone should revert; copy the older version into a personal prompt if only you want the old behaviour. ## Using a prompt in chat The chat composer has a prompt picker at its base. Open it, search or filter to find the prompt you want, and click it to paste the content into the composer. The prompt is now your message — edit it, attach files, add context, send. Once sent, the prompt acts the way any composer input does; Tale does not track which chats used which prompts. Some prompts contain template variables — placeholders like `{{customer_name}}` or `{{topic}}`. The picker prompts you for each variable before pasting; the resulting content is the prompt with the placeholders filled in. Variables are declared in the prompt's content with the `{{variable_name}}` syntax. ## Limits and lifecycle A prompt's content has a size limit — the library form shows the current usage against the maximum, and the Save button is disabled if you exceed it. The limit is generous enough for most prompts to fit; if you hit it, the right answer is usually that the prompt is two prompts. Deleting a prompt is reversible only through the version history if you saved it once before. Personal prompts are deleted permanently on account deletion; team prompts survive team reorganisation unless the team is deleted; global prompts survive everything except an explicit delete. ## Where this fits The prompt library is the lightest available form of reuse in Tale — lighter than an agent (which carries instructions, knowledge, and tools), lighter than a skill (which packages instructions and a script). Reach for a prompt when the reuse is just the text; reach for an agent when the reuse is a configured behaviour. The natural next read is [Starters and prompts](/platform/chat/starters-and-prompts) for how prompts surface in the chat composer alongside an agent's own starters. # Authentication Source: https://tale.dev/docs/self-hosted/configuration/authentication Tale ships four sign-in modes that an operator picks per instance. The default is local password, with one user per email; Microsoft Entra and generic OIDC delegate identity to an external provider; trusted headers hands the responsibility to a reverse proxy already terminating SSO upstream. The decision is permanent in the sense that it shapes how users are provisioned — switching modes after rollout is possible, but every existing user has to be re-mapped to the new identity source. Local password and trusted headers are switched by env vars ([Environment reference](/self-hosted/configuration/environment-reference)); Microsoft Entra and generic OIDC are configured per organisation inside the running app. This page is the mode-by-mode walkthrough — when to choose each, what it changes for the user, what breaks when it is misconfigured. ## Local password (default) Local password is the mode you get if you set nothing. The platform stores a bcrypt hash in Postgres, signs the session with `BETTER_AUTH_SECRET`, and the user signs in with an email and password the admin invites them with. No external identity provider is involved. Reach for it on small instances and air-gapped deployments where adding an IdP is more friction than it solves. The cost: password reset goes through the admin (or through email if `SMTP_*` is configured), and there is no SSO story. ```bash # .env — no flags needed for local password HOST=localhost SITE_URL=https://localhost BETTER_AUTH_SECRET=... ``` ## Microsoft Entra The Microsoft Entra mode adds a **Continue with SSO** button to the sign-in screen and accepts users from a tenant you control. There is no env-var switch: the connection is configured per organisation under **Settings > Enterprise SSO** once the platform is up — pick the **Microsoft Entra ID** protocol and enter the client ID, client secret, and issuer URL from your app registration. The full walkthrough, including role mapping and group-to-team sync, is [Enterprise SSO and provisioning](/platform/admin/enterprise-sso). Two deployment values must be right before the flow can work: `SITE_URL`, because the sign-in redirect URL is derived from it, and `BETTER_AUTH_SECRET`, which signs the OAuth state. The redirect URI to register in Entra is `${SITE_URL}${BASE_PATH}/http_api/api/sso/callback` — the settings page shows the exact URL to copy, and it must match byte-for-byte or Entra rejects the sign-in with `AADSTS50011`. The tenant ID in the Entra app registration narrows who can sign in; a multi-tenant registration accepts anyone with a Microsoft account, which is rarely what you want. ## Generic OIDC Generic OIDC accepts any spec-compliant identity provider — Keycloak, Authentik, Okta, Google Workspace. Configuration lives on the **Single Sign-On** card under **Settings > Integrations**: pick the **Generic OIDC** provider type, enter the issuer URL, client ID, and client secret, and Tale reads the authorization, token, and userinfo endpoints from the issuer's `.well-known/openid-configuration` document. The flow uses the standard Authorization Code grant with PKCE (S256). Tale stores no secret on disk for OIDC; the client ID and client secret live in the encrypted credential store. The redirect URI to register with your provider is `${SITE_URL}/http_api/api/sso/callback`. Identity providers disagree on where claims live, so the card lets you point Tale at yours. The **Email claim**, **Name claim**, and **Groups claim** fields take a claim name or a dot path into the userinfo response — Keycloak's realm roles, for example, sit at `realm_access.roles`. Role mapping rules assign platform roles at sign-in: a **Group** rule matches the user's groups against a wildcard pattern (`platform-admin*` → Admin), a **Claim** rule matches any claim resolved by dot path. **Auto-provision teams** mirrors the groups your provider returns as Tale teams on every sign-in, minus the groups you exclude. A worked Keycloak example: create a confidential client `tale-platform` with the redirect URI above, add a Group Membership mapper so the client emits `groups` in userinfo, then in Tale set the issuer to `https://keycloak.example.com/realms/<realm>`, add a group rule `platform-admin*` → Admin, and click **Test connection** — it validates discovery before anything is saved. This is the mode for teams that already run an IdP and want their existing identity surface in Tale. ## Trusted headers Trusted headers is the mode for sites that terminate SSO at an upstream reverse proxy — oauth2-proxy, Pomerium, Authelia. The proxy authenticates the user and forwards identifying headers (`X-Auth-Request-Email`, `X-Auth-Request-Preferred-Username`); Tale trusts those headers and creates or updates the user record on the fly. ```bash # .env TRUSTED_HEADERS_ENABLED=true ``` The threat model is delicate. Anything that can reach the platform container with those headers becomes the user named in them. Restrict the platform port so only the proxy can speak to it (a Docker network or a host firewall rule), and never expose the platform container directly to the internet when this mode is on. ## Where this fits The four modes are mutually exclusive in spirit but technically additive — Microsoft Entra and trusted headers can coexist on the same instance if your IdP story is mid-migration. The full per-mode trade-off table lives in [Members and roles](/platform/admin/members-and-roles) on the user side; this page covers the operator's switch. The next configuration page worth reading is [Providers](/self-hosted/configuration/providers) — once users can sign in, you still need at least one model provider wired up before they can do anything. # Data residency Source: https://tale.dev/docs/self-hosted/configuration/data-residency A self-hosted Tale deployment runs on infrastructure you already control, so its data lives on your hosts by default. **Data residency** is for the case where you want individual data stores pointed at your own managed Postgres or object storage instead of the bundled containers — for example to keep document text in a database your team operates, or uploaded files in your own S3 bucket. The knowledge corpus runs as its own container (`knowledge-db`) precisely so it can be relocated or replaced independently of the operational database — it is the store most residency requirements care about. Administrators configure this in **Settings > Data residency**; the change is written to a single deployment-level config file and **takes effect when the affected containers restart**. This page covers what can be relocated, the one prerequisite that bites (ParadeDB), how the configuration is stored and applied, and how to restart safely. ## Enabling editing Viewing the page is open to any organization owner or admin, but **editing** — repointing a data store, saving secrets, running a connection test, or applying a restart — is restricted to a named allowlist of operators. List their sign-in emails (comma-separated) in `.env` and restart: ```bash TALE_DEPLOYMENT_CONFIG_ADMINS=alice@example.com,bob@example.com ``` With the allowlist empty or unset, **Settings > Data residency** still shows the current configuration to administrators, but read-only — Save, Test, and Apply & restart refuse for everyone. Only a signed-in admin whose email is on the list gets an editable page; the page tells you which email to add. The entrypoints always consume the config file regardless of the allowlist, so an operator who prefers to hand-edit the file on disk can do so without naming any UI editors. ## What you can relocate Three stores, each independent and optional. An absent setting means "use the bundled default" — so a fresh deployment with no config is unchanged. - **Knowledge database** — the knowledge corpus: document metadata, the extracted chunk text, embeddings, the BM25 index, the semantic cache, and the crawled web pages. It ships as the bundled `knowledge-db` container (`tale_knowledge`, with the `private_knowledge` and `public_web` schemas) and is the store most residency requirements care about, because it holds your document content. Point it at your own managed Postgres to keep the corpus on infrastructure your team operates. - **File storage** — where uploaded files (the original blobs) live. By default they sit on the local Convex volume; you can point them at an external S3-compatible bucket. - **Application database** (advanced) — the operational Convex database (the bundled `db` container). The Convex backend derives this database's name from `INSTANCE_NAME` (`tale_platform`) and connects on host:port only, so the external Postgres must contain a database named exactly `tale_platform`. Its TLS mode is fixed by the Convex driver and is not configurable. > Note: the knowledge database and the application database are two separate Postgres instances — moving one does not touch the other. Relocating the knowledge database moves the extracted text and embeddings; the original uploaded files move only when you also relocate **File storage** to S3. ## The ParadeDB prerequisite The knowledge database uses two Postgres extensions: `vector` (pgvector) for embeddings and `pg_search` (ParadeDB) for full-text/BM25 hybrid search. An external knowledge Postgres **must run ParadeDB** (which bundles both) for full search quality. If you point it at a plain Postgres that has only `pgvector`, indexing and vector search still work, but hybrid search degrades to **vector-only** — the BM25 leg is silently skipped. The **Test connection** button reports both `pgvector` and `pg_search` availability so you can see this before you commit. The external knowledge database must already exist (it can have any name you enter — `tale_knowledge` by convention) with the `private_knowledge` and `public_web` schemas; the baseline schema migrations live in [`services/db/migrations/`](https://github.com/tale-project/tale/tree/main/services/db/migrations) and are applied via dbmate when the database comes up. ## File storage on S3 External file storage is all-or-nothing across Convex's storage use-cases, so you provide **five buckets** — files, exports, snapshot-imports, modules, and search — plus a region and credentials. For S3-compatible services (MinIO, Cloudflare R2) set the endpoint and enable path-style addressing. > **Greenfield only.** Switching file storage from local to S3 does **not** migrate the blobs already on the local volume — Convex will look for them in the bucket and not find them. Set S3 at initial deployment, or copy the existing local storage into the bucket out of band before switching. ## How the configuration is stored Saving writes two files at the config root (not under an org directory): - `deployment.json` — the non-secret config (hosts, ports, buckets, modes). - `deployment.secrets.json` — the database passwords and S3 keys, SOPS-encrypted (see [Secrets with SOPS](/self-hosted/configuration/secrets-with-sops)). At boot the `convex` entrypoint reads these and derives its connections before starting. Knowledge ingestion and retrieval run inside the Convex backend, so it is the only container that opens the knowledge-database connection — there is no separate retrieval service to configure. The contract is **fail-closed**: a present-but-unparseable `deployment.json`, an undecryptable secret, or a config missing required fields **aborts startup** rather than silently falling back to the bundled database — mis-routing regulated data is worse than not starting. An absent file is the normal default path. ## Applying a change: restart The config is read at boot, so a save does not take effect until the **`convex`** container restarts (the platform itself does not need restarting). Two ways: - **Manual** — `docker compose restart convex`, or `tale deploy --services convex` for a zero-downtime blue-green roll. - **One-click** — enable the opt-in `controller` service (`docker compose --profile controller up -d`). It is a small internal-only sidecar that restarts the allowlisted `convex` service on an HMAC-signed request from the app, so the browser-facing platform never needs Docker-socket access. With it running, the **Apply & restart** button does the bounce for you; set `CONTROLLER_TOKEN` (shared with the platform) and `CONTROLLER_URL` in `.env`. Without it, the button shows the manual command. The relevant environment variables are `TALE_DEPLOYMENT_CONFIG_ADMINS` (the comma-separated email allowlist of operators allowed to edit), and — only when running the one-click `controller` — `CONTROLLER_TOKEN` (the shared HMAC secret) and `CONTROLLER_URL` (e.g. `http://controller:8004`). Set them in `.env`. See also [Environment reference](/self-hosted/configuration/environment-reference) and [Secrets with SOPS](/self-hosted/configuration/secrets-with-sops). # Environment reference Source: https://tale.dev/docs/self-hosted/configuration/environment-reference Tale reads its configuration from a single `.env` file at the repo root. About a dozen variables are mandatory at first boot; the rest tune behaviour. This page lists every variable the [`.env.example`](https://github.com/tale-project/tale/blob/main/.env.example) ships with, what it defaults to, and which surface in the product consumes it. Groups are ordered by when you first need them: domain identity, TLS, secrets, database, instance, observability, provider encryption. If a variable changes value, restart the platform container (`docker compose restart tale-platform tale-convex`) for it to take effect. ## How to read this page Each group is a `Name | Default | Description` table. Variables marked **Required** must be set before `docker compose up` succeeds. Variables marked **Optional** can be left unset; the column's description names what disabling the feature does. The `.env.example` file ships with inline comments that explain each variable in context; this page is the structured, grouped reference for the same set. ## 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. | | `BASE_PATH` | unset | **Optional.** Path prefix for subpath deployments behind a reverse proxy (e.g. `/app`). Leave unset for root deployments. | The `SITE_URL` must match what the user types in the browser exactly. A trailing slash, a missing port, or `http` instead of `https` will break the auth callback and produce sign-in loops. ## TLS | Name | Default | Description | | ----------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------- | | `TLS_MODE` | `selfsigned` | One of `selfsigned`, `letsencrypt`, `external`. See [TLS and domains](/self-hosted/configuration/tls-and-domains) for trade-offs. | | `TLS_EMAIL` | unset | Contact email for Let's Encrypt notifications. Optional but recommended in production. | `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 | **Required.** Base64 secret for the Better Auth session signer. Generate with `openssl rand -base64 32`. Rotating invalidates every session. | | `ENCRYPTION_SECRET_HEX` | example value in shipped file | **Required.** 32-byte hex key. AES-256 key for OAuth and integration credentials and HKDF input for the guardrails secret box. Generate with `openssl rand -hex 32`. Rotating invalidates every DB-stored ciphertext; operators must re-enter affected secrets. | | `INSTANCE_SECRET` | example value in shipped file | **Required.** Used to derive the Convex admin key for `tale deploy`. Deploy fails if unset. | Replace the values that ship in `.env.example` before exposing the instance — they are intentionally insecure placeholders. ## Database Tale runs two Postgres databases: the operational store (`db`, port 5432) behind the Convex backend, and the knowledge corpus (`knowledge-db`, port 5433) that holds document chunks, embeddings, and crawled pages. Both are ParadeDB and share `DB_PASSWORD`, but they are independent — point either at external infrastructure on its own. | Name | Default | Description | | ------------------------ | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DB_PASSWORD` | `tale_password_change_me` | **Required.** Password for the self-hosted Postgres user. Change before production. Used by both database containers. | | `POSTGRES_URL` | constructed from `DB_PASSWORD` | **Optional.** Override the auto-constructed operational-database URL. Use when pointing at an external Postgres or a non-standard host/port. | | `KNOWLEDGE_DATABASE_URL` | `postgresql://tale:${DB_PASSWORD}@knowledge-db:5432/tale_knowledge` | **Optional.** Connection URL the Convex backend uses for the knowledge corpus. Override to relocate the corpus to your own managed ParadeDB — the data-residency-sensitive store moves independently. | | `KNOWLEDGE_DB_NAME` | `tale_knowledge` | **Optional.** Name of the knowledge database. The bundled `knowledge-db` container creates this database on first boot. | The auto-constructed operational form is `postgresql://tale:${DB_PASSWORD}@db:5432`. Convex expects this URL without a database name; the name is derived from the instance configuration. The knowledge corpus lives in `tale_knowledge` with the `private_knowledge` and `public_web` schemas; the **Settings > Data residency** UI writes a richer per-store config than these raw variables, covered in [Data residency](/self-hosted/configuration/data-residency). ## Observability | Name | Default | Description | | --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `SENTRY_DSN` | unset | Sentry DSN for error tracking. Leave unset to disable. Compatible with self-hosted GlitchTip and Bugsink. | | `SENTRY_TRACES_SAMPLE_RATE` | unset | Optional sample rate for performance traces (`0.0`–`1.0`). Default behaviour depends on the deployment. | | `METRICS_BEARER_TOKEN` | unset | Bearer token required to access the Prometheus `/metrics/*` endpoints. Leave unset to keep metrics endpoints unreachable from outside. | Setting `METRICS_BEARER_TOKEN` exposes two endpoints behind the token: `/metrics/platform` and `/metrics/convex` (Convex's 261 built-in metrics, which now carry the RAG and crawl timings as well). See [Observability config](/self-hosted/configuration/observability-config) for the scrape config. ## Provider secrets encryption | Name | Default | Description | | ------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `SOPS_AGE_KEY` | unset | Inline age secret key. Encrypts `providers/*.secrets.json`. Default mode after `tale init`. Multiple keys are not supported inline. | | `SOPS_AGE_KEY_FILE` | unset | Path to a file with one or more age keys (one per line; `#` comments allowed). Required for key rotation. Mutually exclusive with the inline form. | When both age vars are unset, Tale stores `providers/*.secrets.json` as plaintext JSON at mode 0600. Reach this mode only when the host disk is encrypted at rest or the files are produced by external tooling (a Kubernetes Secret mount, a Vault template). Rotating an age key is appending the new key, re-saving each provider in the UI, then dropping the old key. See [Secrets with SOPS](/self-hosted/configuration/secrets-with-sops) for the full rotation walk. The env-var key source needs no environment-level switch: a provider can read its key from an environment variable instead of a secrets file, as long as the variable is named with the reserved `TALE_PROVIDER_KEY_` prefix (any other name is rejected). The mechanism — the prefix gate, resolution order, the 40-character cap, the restart requirement — is documented in [Providers](/self-hosted/configuration/providers#environment-variable-key-source). A [token source](/platform/admin/token-sources) follows the same pattern for the broker auth secret it sends _to the broker_: it reads from an encrypted `token-sources/<slug>.secrets.json` sidecar, or from an environment variable named with the reserved `TALE_TOKEN_SOURCE_` prefix (any other name is rejected, so the field can never point at a deployment secret). The variable is per-source; define it here or in your secret manager so both the platform and the Convex backend can read it. ## Feature flags Optional toggles for features not enabled by default. Each flag turns one feature on or off at boot; toggling requires a restart of the platform container. | Name | Default | Description | | ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- | | `TRUSTED_HEADERS_ENABLED` | `false` | Enables the trusted-headers auth mode (identity supplied by the reverse proxy). | | `FILE_EVENTS_ENABLED` | `false` | Enables file-watching events for the OneDrive-sync integration. | | `TALE_DEPLOYMENT_CONFIG_ADMINS` | unset | Comma-separated email allowlist of operators allowed to edit deployment data residency. Empty/unset = read-only for all admins. | ## RAG retrieval tuning Optional knobs for knowledge-base search. The in-process RAG path (Convex node-actions) re-scores results with a cross-encoder when re-ranking is on. All carry the `RAG_` prefix and are read by the `platform` and `convex` containers at boot; after changing one, run `docker compose restart platform convex` for it to take effect. | Name | Default | Description | | ---------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `RAG_RERANKING_ENABLED` | `false` | Re-scores the merged BM25 + vector candidates with a cross-encoder before results are returned. Improves precision at the cost of per-query latency. | | `RAG_RERANKING_MODEL` | `cross-encoder/ms-marco-MiniLM-L-6-v2` | Cross-encoder model identifier passed to the rerank provider. | | `RAG_RERANKING_PROVIDER` | `local` | Must be set to `api` to enable re-ranking — it posts the candidates to an external `/rerank` endpoint (Cohere/Jina-compatible). `local` is no longer supported and fails fast. | | `RAG_RERANKING_TOP_K` | `10` | Maximum number of results the reranker returns. The response never exceeds the request's own `top_k`. | | `RAG_RERANKING_CANDIDATES` | `30` | Size of the candidate pool fed to the reranker. A wider pool improves re-scoring quality and costs proportionally more time per query. | | `RAG_RERANKING_API_BASE_URL` | unset | Base URL for the rerank provider; the platform calls `{base_url}/rerank`. Required when re-ranking is enabled. | | `RAG_RERANKING_API_KEY` | unset | Bearer token sent to the external rerank endpoint. Leave unset for unauthenticated endpoints. | Re-ranking ships disabled because it adds per-query latency and depends on an external endpoint. Enable it — by setting `RAG_RERANKING_PROVIDER=api` and pointing `RAG_RERANKING_API_BASE_URL` at a hosted rerank service — when retrieval precision matters more than response time. There is no in-process model to download or cache; with re-ranking off, search returns the plain merged BM25 + vector ranking. ## 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](/platform/admin/governance/policies-and-limits); idle sessions under that policy are revoked by a sweep that runs about every five minutes. ## Where this fits The variables here are the operator's contact surface; the UI surface that consumes most of them lives under [Platform admin](/platform/admin/overview). Provider keys are the one half-and-half: the keys themselves live in `providers/*.secrets.json`, but the UI under **Settings > AI providers** is how you add and rotate them in practice. The next read worth queuing is [Providers](/self-hosted/configuration/providers) — it covers the file form, the SOPS modes, and the resolve-and-failover behaviour. # Observability config Source: https://tale.dev/docs/self-hosted/configuration/observability-config Tale ships three observability seams: stdout logs from every container, Prometheus-format metrics behind a bearer token, and optional Sentry error reporting. The defaults are loud enough to spot a crash and quiet enough to fit in a single host's journald; the production knobs below add the structured paths your existing monitoring stack can scrape. None of the three send anything off-host unless you configure them to. This page covers the server-side switches. The operator-facing alert playbook lives in [Operations](/self-hosted/operate/observability/operations), and the symptom-first lookup in [Troubleshooting](/self-hosted/operate/observability/troubleshooting). ## Logs Every container writes structured JSON or console logs to stdout, captured by Docker's default `json-file` driver with a 10 MB-per-file, 3-file rotation. The log destination is a function of how you deploy: - Single host with journald — `journalctl -u docker` carries the lot. - Single host without journald — `docker compose logs -f <service>` for live tailing. - Aggregator (Loki, Vector, Fluent Bit) — point the Docker logging driver at it via `daemon.json`. Tale does not ship a log shipper. The driver swap is the supported integration point. ## Metrics The Caddy proxy exposes three metrics paths gated by a single bearer token: | Path | Source | What's inside | | -------------------- | --------------- | ----------------------------------------------------------------------------------- | | `/metrics/platform` | `tale-platform` | HTTP latency, route counters, Node process metrics, response-time SLA target gauges | | `/metrics/convex` | `tale-convex` | 261 built-in Convex metrics, plus the RAG and crawl timings | | `/metrics/sla-rules` | `tale-platform` | Generated Prometheus recording + alerting rules for the response-time SLAs | Knowledge work (RAG search, document ingestion, web crawling) runs inside the Convex backend now, so its timings ride the `/metrics/convex` series rather than a separate endpoint. Set `METRICS_BEARER_TOKEN` in `.env` to enable these endpoints; leave it unset to keep them returning 401 to every request. The `/metrics/sla-rules` path is a read-only YAML rules file you load into Prometheus, not a scrape target — the thresholds it carries are documented in [Operations](/self-hosted/operate/observability/operations). Anything other than the listed paths returns 401 too, so a misrouted scraper does not accidentally see the platform's internal health endpoints. A working Prometheus scrape stanza: ```yaml scrape_configs: - job_name: tale-platform scheme: https metrics_path: /metrics/platform authorization: credentials: <METRICS_BEARER_TOKEN> static_configs: - targets: ['tale.example.com'] ``` Duplicate the stanza per path, or use a single job with `relabel_configs` if you prefer. ## Error tracking with Sentry Sentry is opt-in via `SENTRY_DSN`. Self-hosted GlitchTip and Bugsink work too, since they speak the same DSN format. The platform and the convex containers both read the DSN and tag events with the container name. ```bash # .env SENTRY_DSN=https://your-key@your-sentry-host/project-id SENTRY_TRACES_SAMPLE_RATE=0.1 ``` The sample rate caps performance traces; leave it unset for the default 1.0 in development and tighten it (0.05–0.2) in production. Stack frames are sent unredacted, so point the DSN at infrastructure you control if your error payloads are sensitive. ## What does not ship yet OpenTelemetry traces are not built into the containers. The data is reachable indirectly — Convex action durations and HTTP route timings come through the Prometheus metrics — but there is no OTLP exporter on the box today. If you need full trace export, run an OpenTelemetry Collector alongside Tale and scrape the Prometheus endpoints from it. ## Where this fits The three seams above are the contact points with the rest of your monitoring stack; the alert thresholds and the oncall checklist live in [Operations](/self-hosted/operate/observability/operations). If something is on fire right now and you need the symptom-first index, jump to [Troubleshooting](/self-hosted/operate/observability/troubleshooting). # Providers Source: https://tale.dev/docs/self-hosted/configuration/providers Tale stores every model provider as two files under `providers/` — a `<name>.json` for the public shape (base URL, models, capabilities) and a `<name>.secrets.json` for the API keys. The split exists so the config is safe to commit and the secrets get the encrypted treatment SOPS gives them. The `tale-platform` container reads both at boot and watches them for changes; restarting the container is not required to pick up edits. The reference is the file format on disk and the order operations follow when adding a provider. The UI-driven flow ("Settings > Providers") sits on top of the same files; both produce identical results. ## The config file `providers/<name>.json` describes the provider's public shape. The `displayName` shows up in the UI, the `models` array names everything reachable through this provider, and each model declares its tags (`chat`, `vision`, `embedding`, `transcription`, `text-to-speech`). ```json { "displayName": "OpenRouter", "description": "Chat, vision, embeddings, voice, and image generation through one key.", "baseUrl": "https://openrouter.ai/api/v1", "secretsEnv": "TALE_PROVIDER_KEY_OPENROUTER", "defaults": { "transcription": "openai/whisper-1", "text-to-speech": "openai/gpt-4o-mini-tts-2025-12-15" }, "models": [ { "id": "openai/whisper-1", "displayName": "Whisper v1", "tags": ["transcription"], "transcriptionMode": "json-base64", "cost": { "centsPerAudioMinute": 0.6 } } ] } ``` The full set of fields lives in [`builtin-configs/providers/`](https://github.com/tale-project/tale/tree/main/builtin-configs/providers). The shipped default is a single `openrouter.json` that covers chat, vision, embeddings, transcription, text-to-speech, and image generation — one key for everything — with curated presets across the common providers (Anthropic, OpenAI, Google, xAI, Mistral, Meta, DeepSeek, Qwen, Cohere, Amazon, Perplexity, and more). To call a vendor directly instead of through OpenRouter, add another file (for example an `openai.json` pointed at `https://api.openai.com/v1`); see [Models out of the box](/platform/models) for the full default catalogue. `transcriptionMode` selects how a `transcription` model's request body is shaped: `json-base64` (OpenRouter's `input_audio` envelope) or, when omitted, `multipart` — the OpenAI/Whisper `multipart/form-data` upload that vLLM, LocalAI, and a direct OpenAI key also expect. Set it to match whichever transcription endpoint you point at. ### Model capabilities and auto-sync Each model may declare optional metadata that complexity-based routing and the Adaptive Reasoning Governor use: `contextWindow`, `maxOutputTokens`, `qualityScore` (0–1), `tier` (`draft`/`standard`/`frontier`), `routingTags` (preferred domains), `reasoning` (the steering knob — `effort` or `budgetTokens`), and `promptCaching` (`auto-server` or `explicit-breakpoints`). Anything you omit is filled from OpenRouter's catalog at runtime; anything you set wins. Set `"hidden": true` to drop a model from the pickers (chat composer, agent creation) while keeping it resolvable for agents that already reference it — the way to retire a superseded version without breaking existing workflows. These fields also stay current on their own: once a week Tale merges fresh OpenRouter facts into each org's provider config — adding newer flagship versions, hiding superseded ones, and refreshing capability values — touching only the fields you have not customised. Turn it off per-org with the **Weekly auto-sync** toggle on the model-catalog card under **Settings > Providers**. When `maxOutputTokens` is unset, Tale caps output at **32,768** tokens. Set `0` to send no cap at all. Lower it to your deployment's real ceiling if the provider rejects large values (e.g. an Azure GPT-4o deployment returning `max_tokens is too large`). ### Request body map Some endpoints expect a slightly different request shape than the standard OpenAI-compatible one. A model — or the provider, as a default — may declare a `requestBodyMap` that rewrites the final request body on the way out: ```json { "requestBodyMap": { "rename": { "max_tokens": "max_completion_tokens" }, "remove": ["frequency_penalty"] } } ``` `rename` maps a field name to another (applied first); `remove` drops fields the endpoint rejects. A per-model `requestBodyMap` overrides the provider-level one on conflicting keys. Unlike `providerOptions`, these instructions never reach the provider — they rewrite the body in place, so this is the supported way to change a reserved field like `max_tokens`. The classic case is an OpenAI / Azure **reasoning** deployment (o-series, GPT-5), which rejects `max_tokens` and requires `max_completion_tokens`. If you flag the model as a reasoning model (set its `reasoning` knob), Tale applies that exact rename automatically — so you only need `requestBodyMap` for other endpoint quirks. ## The secrets file `providers/<name>.secrets.json` is a flat JSON object with the API key under the field name the provider expects: ```json { "apiKey": "sk-..." } ``` With `SOPS_AGE_KEY` or `SOPS_AGE_KEY_FILE` set, this file is stored encrypted on disk. With both unset, it is plaintext at file mode 0600 — reach that mode only on disks encrypted at rest. The full encryption walkthrough lives in [Secrets with SOPS](/self-hosted/configuration/secrets-with-sops). ## Environment-variable key source If your secrets already live in Kubernetes Secrets, Vault, or a cloud secret manager, you can point a provider at an **environment variable** instead of a secrets file. Add a `secretsEnv` to the config file (it names the variable; the name itself is not a secret, so it stays in the committable config): ```json { "displayName": "OpenRouter", "baseUrl": "https://openrouter.ai/api/v1", "secretsEnv": "TALE_PROVIDER_KEY_OPENROUTER", "models": [ { "id": "openai/gpt-4o", "displayName": "GPT-4o", "tags": ["chat", "vision"], "secretsEnv": "TALE_PROVIDER_KEY_OPENAI_DIRECT" } ] } ``` Two guardrails apply: - **Reserved prefix (required).** The variable name must start with `TALE_PROVIDER_KEY_` (e.g. `TALE_PROVIDER_KEY_OPENROUTER`). Any other name is rejected, so a config that names a non-prefixed variable resolves to no key. This stops a config-write actor from pointing `secretsEnv` at an unrelated deployment secret (e.g. `SOPS_AGE_KEY`) and having it sent to a provider URL. The prefix gate is hardcoded — there is no deployment switch to set. - **Length.** The name must be 40 characters or fewer — the platform syncs env vars to its Convex backend, which caps variable names at 40. Resolution order, highest first: model-level `secretsEnv` → provider-level `secretsEnv` → the secrets file (`modelKeys[id]` then `apiKey`). Each tier is skipped when it yields nothing, so a configured-but-empty variable falls back to the file. Env values are trimmed (a trailing newline from a mounted secret is a common cause of `401`s). Unlike the secrets **file** — which the watcher re-reads on every request — an env-var **value** is read once at process start. Changing it requires **restarting the `tale-platform` container** (it re-syncs env to Convex at boot). The platform syncs the variable to the Convex backend automatically, so the in-process RAG and crawler actions pick it up from the same sync — there is no separate service to recreate. ## Adding a provider The order matters — the watcher reads the config file first to know the provider exists, then resolves the secret on the first request. 1. Drop the config file at `providers/<name>.json`. 2. Drop the secrets file at `providers/<name>.secrets.json` (encrypted or plaintext per your SOPS mode). 3. Refresh **Settings > Providers** in the UI — the new provider appears within a few seconds (the watcher polls every 2 s). 4. Pick the new provider's default model under **Settings > Models** so agents that resolve "default" land on it. If the config file is malformed, the platform logs a warning and skips the provider; the rest stay reachable. ## Swapping a key Edit the secrets file in place — the watcher picks up the change and the next request to that provider uses the new key. Existing in-flight requests still hold the old key; cancel and retry to force re-resolution. (Keys sourced from an [environment variable](#environment-variable-key-source) are the exception: changing the value requires a container restart, not just a file edit.) ## Disabling a provider Either delete both files, or set `"disabled": true` at the top level of the config. Disabling keeps the file on disk for later (handy when you want to keep the model list around but stop billing); deleting removes it entirely. Agents that named the provider explicitly start failing at the next request — switch them to a fallback first. ## Where this fits Providers are the one half-and-half between server config (this page) and UI (the **Providers** screen). The keys themselves live in `providers/*.secrets.json`; the SOPS handling lives in [Secrets with SOPS](/self-hosted/configuration/secrets-with-sops). The model-level defaults that agents resolve against are documented under [Platform > Models](/platform/models). # Retention Source: https://tale.dev/docs/self-hosted/configuration/retention Retention in Tale is the policy that deletes old data on a schedule — chats, documents, audit logs, workflow executions, token-usage ledger rows. The operator sets bounds (minimums and maximums) per category; each org's admin picks the actual retention window inside those bounds via **Settings > Governance > Retention policy**. The split exists so a hosting team can enforce compliance floors without micromanaging every tenant. This page covers the operator surface. The admin-facing controls and the per-category descriptions live in [Governance > Retention policy](/platform/admin/governance/policies-and-limits). ## How the bounds work Each retention category — chat threads, documents, customers, vendors, prompt templates, ledger rows, audit logs, workflow executions, workflow trigger logs, login attempts — has a `min` and a `max`. An org admin sets a value inside that window. Tightening the floor across an existing instance is a multi-step flow: operator proposes the new bound, every affected admin sees a banner, the change applies once accepted. | Category | Typical floor | Why | | ----------------------- | ------------- | ---------------------------------------------- | | Chat history | 30 d | Most users want recent context, not forever | | Documents | 1 y | Knowledge tends to age out slowly | | Audit logs | 1 y minimum | Compliance frameworks expect a year | | Token-usage ledger | 90 d | Analytics and budget reports rely on rows | | Workflow execution logs | 30 d | Debugging rarely reaches further back | | Login attempts | 30 d | Brute-force investigation needs the audit tail | The shipped defaults are loose; tighten per your compliance posture. ## Where you set bounds Under the org-first layout, retention bounds are **per-org**: edit `retention.json` directly inside an org's subtree under `TALE_CONFIG_DIR` (defaults to `/app/data/` inside the platform container, so the file lives at `/app/data/<org>/retention.json`, e.g. `/app/data/default/retention.json`). Each org has its own file; the `default` org's file is the template a fresh deployment picks up on first boot. ```json { "chatHistory": { "min": 30, "max": 730, "unit": "days" }, "documents": { "min": 1, "max": 3650, "unit": "days" }, "auditLog": { "min": 365, "max": 3650, "unit": "days" }, "tokenLedger": { "min": 90, "max": 1095, "unit": "days" } } ``` The platform container watches the file; changes propose a bounds update for every existing org. Admins see the proposal in their **Retention policy** screen and apply it themselves. The propose-then-apply step is deliberate: tightening a floor shortens history, which is a destructive action no operator should land silently on every tenant. The admin-chosen retention windows live in a separate file, `retention-policy.json`, alongside the bounds in the same `governance/` folder. It holds flat `<category>Enabled` / `<category>RetentionDays` fields (e.g. `"auditLogEnabled": true, "auditLogRetentionDays": 730`), not the `min`/`max` bounds. That file is written by **Settings > Governance > Retention policy** in the app, so admins normally never edit it by hand — keep it distinct from the operator-owned bounds file. ## The retention sweep A scheduled cron inside `tale-convex` runs the actual deletion. Each category is swept independently — a slow run on one does not block the others. Deletions are audited (every category has its own `*.retention_deleted` event), and restoring an entity inside its grace window is possible from **Trash** before the final sweep. Audit log entries are themselves subject to retention, but their floor is enforced per-deployment, not per-org: the strictest (shortest) audit-log retention across all orgs is what actually runs. A stricter tenant pulls everyone tighter — keep this in mind on multi-tenant instances. ## Legal hold A legal hold freezes retention for a specific scope: a single thread, a customer record, or an entire organization. Held entities skip the sweep until the hold is released. The hold itself is audited; org-wide holds are loud enough that the UI surfaces a confirmation before they apply. ## Where this fits The bounds file is the operator's lever; the per-category windows the admin sees are documented in [Retention policy](/platform/admin/governance/policies-and-limits). If you are setting bounds against a compliance framework (GDPR, HIPAA, SOC 2), the audit-log floor is usually what auditors check first. # Secrets with SOPS Source: https://tale.dev/docs/self-hosted/configuration/secrets-with-sops Tale stores provider API keys in `providers/*.secrets.json` files on disk. The default mode after `tale init` encrypts these files with SOPS using an age key; an alternative mode reads multiple keys from a file (the rotation path); a third mode keeps the files in plaintext at file mode 0600 for environments where the disk is encrypted at rest and rotation is handled externally. This page is the operator's walkthrough of the three modes and the safe rotation path. The env vars that drive the modes are `SOPS_AGE_KEY` and `SOPS_AGE_KEY_FILE` — their reference rows live in [Environment reference](/self-hosted/configuration/environment-reference#provider-secrets-encryption). This page is the longer story. ## The three modes | Mode | Env vars | When to use | | ----------------- | ---------------------------------- | ------------------------------------------------------------- | | Inline age key | `SOPS_AGE_KEY=AGE-SECRET-KEY-1...` | Default after `tale init`. Single host, single key. | | Key file | `SOPS_AGE_KEY_FILE=/path/to/keys` | Required for rotation. One age key per line, `#` comments. | | Plaintext at 0600 | Both unset | Disk encrypted at rest, or external tooling writes the files. | The platform container picks the mode at boot. The inline form is the simplest; the file form is the only one that supports multiple readers (which is what makes rotation possible without downtime); the plaintext form skips SOPS entirely and trusts the filesystem. ## First-boot encrypted mode `tale init` generates an age keypair and writes the private half into `SOPS_AGE_KEY` in your `.env`. Provider secret files written through **Settings > Providers** are encrypted on save: ```bash # Inspect — the file is SOPS-encrypted JSON, not the cleartext API key cat providers/openai.secrets.json # { # "apiKey": "ENC[AES256_GCM,data:...,iv:...,tag:...]", # "sops": { ... } # } ``` Decryption happens in-process when the platform container reads the file. The age key never leaves the platform container's memory. ## Rotating the age key Rotation is the one path the inline form does not cover — only `SOPS_AGE_KEY_FILE` lets you accept ciphertext readable by both the old and the new key during the cutover. The walk: ```bash # 1. Generate a new age key age-keygen -o /etc/tale/age-keys.txt # 2. Append the new key as a second line in the file echo "AGE-SECRET-KEY-1NEW..." >> /etc/tale/age-keys.txt # 3. Point .env at the file and restart the platform container sed -i 's|^SOPS_AGE_KEY=.*|# SOPS_AGE_KEY=|' .env sed -i 's|^# SOPS_AGE_KEY_FILE=.*|SOPS_AGE_KEY_FILE=/etc/tale/age-keys.txt|' .env docker compose restart tale-platform tale-convex ``` Now both old and new keys can decrypt existing files. Re-save each provider's API key under **Settings > Providers** — each save produces ciphertext readable by both keys. Once every provider has been re-saved (the **Last rotated** column in the providers table tells you which still hold old ciphertext), remove the old key from the file: ```bash # 4. Drop the old key line and restart again sed -i '/^AGE-SECRET-KEY-1OLD/d' /etc/tale/age-keys.txt docker compose restart tale-platform tale-convex ``` The order is load-bearing: never remove the old key before every file is re-encrypted, or the platform container will fail to read the still-old files at the next decryption. ## Switching to plaintext When the host disk is encrypted at rest (LUKS, AWS EBS encryption, GCP CSEK) and you do not want a second layer of key management, the plaintext mode is the supported option. Comment out both `SOPS_AGE_KEY` and `SOPS_AGE_KEY_FILE`, restart, and re-save each provider — the files are now JSON at mode 0600. The risk model shifts: a leaked filesystem dump is now a leaked credential dump. Pick this mode only when the disk encryption is real (not a tickbox), and audit the host's backup story to confirm no plaintext snapshot escapes. ## External secret stores When your keys already live in Vault, a cloud secret manager, or Kubernetes Secrets, the first-class pattern is the env-var key source: point each provider at an **environment variable** with `secretsEnv` and let your secret store populate that variable. No cleartext file touches the disk, and the reserved-prefix gate keeps a config-write actor from reading an unrelated deployment secret. The full mechanism — the `TALE_PROVIDER_KEY_` prefix gate, resolution order, and the restart-on-change behaviour — lives in [Providers](/self-hosted/configuration/providers#environment-variable-key-source). The file-mount approach is the legacy alternative: write the cleartext `*.secrets.json` files from the external store and run Tale in plaintext mode. It still works, but it puts the cleartext key on disk and breaks if you save a provider through the UI — the UI overwrites the mount. Prefer the env-var source unless a constraint forces the file form. ## Where this fits This page is the operator's full guide to the SOPS layer; the env-var reference rows are in [Environment reference](/self-hosted/configuration/environment-reference#provider-secrets-encryption), and the provider file format itself in [Providers](/self-hosted/configuration/providers). If a key is leaked, rotation is the same walk above run urgently. # TLS and domains Source: https://tale.dev/docs/self-hosted/configuration/tls-and-domains The `tale-proxy` container is Caddy. It owns TLS termination, host routing, and the metrics auth gate; every browser-facing request lands here first. The three modes — self-signed, Let's Encrypt, external — cover the three deployment shapes most operators reach for, and the variable that switches between them is `TLS_MODE` in your `.env`. The env-var reference rows live in [Environment reference](/self-hosted/configuration/environment-reference#tls). This page is the per-mode walkthrough and the recipes for custom domains and bring-your-own certificates. ## Self-signed (default) `TLS_MODE=selfsigned` runs Caddy with a certificate it generates from its internal CA. The browser warns the first time, and the host needs to trust the cert to suppress the warning — that is intended for local development: ```bash docker exec tale-proxy caddy trust ``` The trust command imports Caddy's CA into the system trust store on the host running the docker daemon. Other machines on the network still see the warning unless they import the CA too. Production never uses this mode. ## Let's Encrypt `TLS_MODE=letsencrypt` lets Caddy issue and renew a real public certificate. Three prerequisites must hold or the issuance loop fails: - The hostname in `HOST` and `SITE_URL` resolves to the host's public IP from the public Internet. - Ports 80 and 443 are reachable from the public Internet (port 80 carries the ACME HTTP-01 challenge). - `TLS_EMAIL` is set to a mailbox you read — Let's Encrypt warns there before expiry. ```bash # .env TLS_MODE=letsencrypt TLS_EMAIL=ops@yourdomain.com ``` The first boot blocks for about a minute while the ACME challenge runs. After that, renewals are automatic 30 days before expiry; failures land in `docker compose logs proxy`. ## External proxy `TLS_MODE=external` makes Caddy serve plain HTTP on the inside, and you front it with your own reverse proxy that terminates TLS upstream. Pick this when: - You already run a CDN or load balancer that handles certificates. - You want to terminate TLS once at the edge of your VPC and run everything internal as plaintext. - Your compliance posture requires a specific certificate authority that Caddy does not support. ```bash # .env TLS_MODE=external SITE_URL=https://tale.yourdomain.com # the URL your users hit ``` The upstream proxy needs `X-Forwarded-Proto: https` set on every request so Tale generates correct redirects and absolute URLs. Without it, sign-in links land on `http://` and the auth cookie's `Secure` flag rejects them. ## Custom domain The domain itself is just `HOST` and `SITE_URL`. The same Caddyfile inside `tale-proxy` reads both at boot. Change them, recreate the proxy container (`docker compose up -d --force-recreate tale-proxy`), and the new domain is live within seconds. Let's Encrypt re-issues for the new name on the next request that hits the new hostname. ```bash # .env HOST=tale.example.com SITE_URL=https://tale.example.com ``` Subpath deployments — Tale behind `https://example.com/app/` — set `BASE_PATH=/app` in addition. The reverse proxy upstream of Caddy strips nothing; Tale handles the prefix itself. ## Bring-your-own certificate For an internal CA or a wildcard cert you already own, mount the cert and key into `tale-proxy` and add a `tls` directive to the Caddyfile: ```yaml # compose.yml override services: proxy: volumes: - ./certs/fullchain.pem:/etc/tale/cert.pem:ro - ./certs/privkey.pem:/etc/tale/key.pem:ro environment: TLS_MODE: external # bypasses Caddy's auto-issuance ``` Then either pre-build a `tale-proxy` image with the custom Caddyfile, or front Tale with your own reverse proxy and stick with `TLS_MODE=external` — both paths are supported and the second is simpler. ## Where this fits The three modes cover the three deployment shapes most teams hit; the env-var rows live in [Environment reference](/self-hosted/configuration/environment-reference#tls). If you are setting up a fresh production host right now, [Production Linux server install](/self-hosted/install/linux-server) walks Let's Encrypt end-to-end with the firewall and DNS steps in order. # Contributing to Docker images Source: https://tale.dev/docs/self-hosted/contributing-docker Every container Tale ships has its Dockerfile in the public source repo. Forks, air-gapped distributions, and one-off patches all start from the same files; this page is the operator's walk through building the images yourself, where the customisation seams live, and how to keep a fork in sync with upstream without diverging on the boring parts. The container architecture lives at [Container architecture](/self-hosted/operate/container-architecture); this page is what you read when the published images do not fit and you need to build your own. ## What the images are The stack is entirely TypeScript — no Python image. Each image has one Dockerfile under `services/<name>/`: | Image | Source path | Base | | ------------------------ | ----------------------------- | ---------------------------- | | `tale-proxy` | `services/proxy/` | Caddy | | `tale-platform` | `services/platform/` | Bun + Debian slim | | `tale-convex` | `services/convex/` | Convex local-backend | | `tale-db` | `services/db/` | ParadeDB (Postgres) | | `tale-sandbox` | `services/sandbox/` | Bun + Docker CLI | | `tale-sandbox-egress` | `services/sandbox-egress/` | Alpine + tinyproxy | | `tale-sandbox-runtime` | `services/sandbox-runtime/` | Bun + Chromium + Playwright | | `tale-sandbox-buildkitd` | `services/sandbox-buildkitd/` | Debian + BuildKit + redsocks | | `tale-controller` | `services/controller/` | Bun + Docker CLI | Both database containers — `db` and `knowledge-db` — build from the same `tale-db` ParadeDB image; the difference is the database each one serves. The LLM gateway, `tale-sandbox-llm-gateway`, is a pinned upstream image (`maximhq/bifrost`), so it has no Dockerfile in the repo. The compose files at the repo root (`compose.yml` for development, the CLI-generated production compose) reference these by `ghcr.io/tale-project/tale/<image>:<tag>`. A local build replaces the registry pull with a `build:` block in compose. ## Building locally A first build of every image takes about 15 minutes on a recent laptop; subsequent builds hit Docker's layer cache and finish in under a minute for the image you changed. ```bash # Build every image in compose.yml docker compose build # Build one image docker compose build platform ``` Set `PULL_POLICY=build` in your environment (or in `.env`) to force compose to build rather than pull the published image. The shipped `compose.yml` defaults to `build`, so a local clone with no overrides already builds; production compose files generated by `tale deploy` default to `always` and pull from the registry. ## The customisation seams The supported extension points for forks are at the Dockerfile level. The image's entrypoint and the configuration files inside it are stable — patch them, build the image, and the rest of the system does not need to know. - **Caddyfile** — `services/proxy/Caddyfile` controls routing and TLS termination. Custom headers, custom subdomains, and custom rate limits land here. - **Platform plop templates** — `services/platform/Dockerfile` runs a build step that bakes in the messages, the schema, and the static assets. A fork that ships custom UI strings or extra routes builds the platform image. - **Sandbox runtime image** — `services/sandbox-runtime/Dockerfile` is the execution environment for `Run code`, web rendering, and document generation; it already carries Chromium and Playwright. A fork that needs an extra system package or a different browser build patches here. - **Sandbox egress proxy** — `services/sandbox-egress/tinyproxy.conf.template` is the proxy config the entrypoint renders at startup: open egress by default, or a default-deny hostname filter when `SANDBOX_EGRESS_ALLOWLIST` is set. A fork that needs different proxy behaviour patches here. What is not a supported seam: the convex backend's application code, including document extraction and the RAG and crawler logic that now live in-process (`services/platform/convex/`), and the platform container's runtime code (`services/platform/app/`). Those files are application code, not configuration — adding a document-format extractor or changing retrieval behaviour is a real fork and rides the upgrade tax. ## Tagging and pushing your own registry For air-gapped or vendored distributions, the path is "build, tag, push to your registry, change the compose `image:` lines." ```bash # Build, tag, push export REGISTRY=registry.internal.example.com/tale docker compose build docker tag ghcr.io/tale-project/tale/tale-platform:latest \ $REGISTRY/tale-platform:vendored-1.0 docker push $REGISTRY/tale-platform:vendored-1.0 ``` The CLI's deploy generates a compose file with the registry path; either patch the generated file post-generation, or skip the CLI and run `docker compose` directly against a compose file you maintain yourself. ## Staying in sync with upstream The cheap path is a fork on GitHub that periodically merges from `tale-project/tale@main`. Conflicts land in the files you patched; the rest carries through clean. The two anti-patterns: - **Patching application code instead of contributing it back.** If the change is broadly useful, upstream a PR — every release tax goes down. - **Pinning to an old base image.** The Caddy, Bun, and Postgres bases pick up security patches on rebuild; pinning the base for "stability" is borrowing trouble. ## Where this fits This page is the contributor-facing seam of the operator story. The architecture overview lives in [Container architecture](/self-hosted/operate/container-architecture); the upgrade workflow that runs the published images is in [Upgrades](/self-hosted/operate/upgrades). If your fork is non-trivial, the conversation worth starting before you write code is the one on the project's Discord or GitHub Discussions — many forks end up being features waiting to land upstream. # Self-hosted Source: https://tale.dev/docs/self-hosted Self-hosted Tale runs on your own infrastructure — on-premises, in your VPC, or air-gapped. Seven containers, your data on your disk, no per-seat billing, and no traffic that crosses to Tale's servers unless you point a provider at one. This section is for operators: the people who decide where Tale runs, install it, configure it, keep it patched, and pick up the pager when something goes wrong. End users of self-hosted instances mostly read the Platform tab — the product surface is identical between editions. ## Pages in this section **[Architecture overview](/self-hosted/overview)** — what each container does, where data lives on disk, what talks to what. **[Install](/self-hosted/install/quickstart)** — quickstart on a laptop, production install on a Linux host, the docker compose reference, first admin setup, the CLI installer. **[Configuration](/self-hosted/configuration/environment-reference)** — every environment variable, provider files, authentication modes, TLS, storage, retention, SOPS-encrypted secrets, observability. **[Operate](/self-hosted/operate/container-architecture)** — upgrades, backups and restore, observability and troubleshooting, security advisories, hardening, release notes format. **[Contributing](/self-hosted/contributing-docker)** — how to build and test a local container change. ## Where this fits Self-hosted is the edition where the operator owns more of the stack. If your team is small and the operational overhead would crowd out product work, [Cloud](/cloud) is the other shape of the same product. If you're standing up a fresh instance right now, [Quickstart](/self-hosted/install/quickstart) is the right next read. # Install the tale CLI Source: https://tale.dev/docs/self-hosted/install/cli-install The `tale` CLI is the recommended way to run and operate Tale. The [quickstart](/self-hosted/install/quickstart) already uses it to stand an instance up locally with `tale init` and `tale dev`; this page is the other half — installing the CLI on a workstation so it can drive a _remote_ instance: deploying new versions, running migrations, and capturing diagnostics without you remembering every `docker compose` invocation. Everything the CLI does can also be done with `docker compose` and `ssh` directly, so a team already deep in its own automation can stay on compose. For everyone else the CLI is the shorter path, and the rest of the self-hosted docs assume it is installed. ## Before you begin You need: - A workstation running macOS, Linux, or Windows 10+. - SSH access to the host your Tale instance runs on, with the operator user able to run `docker compose`. The installer downloads a release binary from GitHub. Corporate networks that block raw-content downloads need to allow `raw.githubusercontent.com` and `github.com`. ## Step 1 — 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 ``` Both installers detect the OS and CPU architecture, pull the matching release binary from the latest GitHub release, and drop it on the `PATH` (`/usr/local/bin/tale` or `%LOCALAPPDATA%\Programs\tale\tale.exe`) — asking for `sudo` when the install directory is not writable. Release binaries ship for macOS on Apple Silicon and Intel, and for Linux on x86_64 and arm64; Windows-on-ARM machines run the x64 binary through the built-in emulation. On an architecture without a released binary, the installer exits with a clear message and points you at building from source. To pin a version, set the `VERSION` environment variable before piping into the installer; to pick the install directory yourself, set `INSTALL_DIR`. | OS | Installer script | | ------- | ------------------------- | | macOS | `scripts/install-cli.sh` | | Linux | `scripts/install-cli.sh` | | Windows | `scripts/install-cli.ps1` | ## Step 2 — Verify ```bash tale --version ``` The CLI prints its version. If the command is not found, the installer dropped the binary outside the `PATH` — the installer output names the destination directory. ## Step 3 — Confirm configuration There is no `tale config set` — everything the CLI needs lives in the project that `tale init` created. Run any `tale` command from inside that directory (the CLI walks up the tree to find `tale.json`), and confirm it resolves: ```bash tale config show ``` The host the proxy answers on, TLS settings, and every secret live in the project's `.env`. To change the host, edit `HOST` there or pass `--host` to `tale dev` / `tale deploy`. To operate a remote host, point your shell's Docker context (or `DOCKER_HOST`) at it — the CLI talks to the same Docker endpoint every `docker` command does. The Convex dashboard admin key is separate from CLI configuration — it never gates sign-up, and it is deterministic (derived from `INSTANCE_NAME` and `INSTANCE_SECRET`, so it stays the same across restarts). Generate it with `tale convex admin` when you want to inspect the backend (see [First admin](/self-hosted/install/first-admin)). ## Step 4 — Run tale deploy ```bash tale deploy ``` `tale deploy` always ships the CLI's own version: it pulls that version's images, restarts the affected containers in the right order, and runs schema migrations — `tale update` is how you move to a different version first. It is the supported replacement for the longer `docker compose pull && docker compose up -d` dance. If you prefer compose directly, the same effect lives in [Upgrades](/self-hosted/operate/upgrades). ## 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**. - Every flag is **optional** — omit it to get the default behaviour. - 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. Run `tale <command> --help` for the authoritative list at 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, human messages on stderr; supported by `status`, `config show`, and `migrate status`. - `--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 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. - `-d, --detach` — run in the background instead of streaming logs. - `-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` — blue-green, zero-downtime deploy of the current CLI version. On the first deploy it prompts for your production domain and Let's Encrypt email (or pass `--host`). - `--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. ### 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 all data volumes into the project backups volume. No arguments. `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 this Tale instance to a new version: update the CLI binary, then sync project files to that version's templates. Run `tale deploy` afterwards to roll the containers. The CLI also self-aligns to the instance version on every command, so this is only needed to deliberately change versions. - `-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 and apply the safe pending data migrations against the running deployment — the same idempotent steps every deploy runs, on demand. The subcommands give granular, reversible control: `migrate status` shows applied and pending migrations, `migrate up [--to <version>]` applies pending ones (destructive steps need `-y, --yes` or `--step`), and `migrate down --to <version>` rolls back. `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 remove the per-user config (`~/.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. - `-f, --force` — skip the confirmation prompt (removes the binary only; the optional cleanups still need `--purge`). - `--purge` — also 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` — manage CLI configuration. Use the `show` subcommand to print the resolved config. ### Advanced `tale auth reset-owner` — reset the owner account credentials. - `-e, --email <email>` — set a new owner email address. - `-p, --password <password>` — set a new owner password. `tale convex admin` — generate a Convex dashboard admin key. No arguments. ## 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. - **The Convex dashboard rejects the admin key.** Sign-up never asks for the key — only the dashboard does. The key is deterministic (derived from `INSTANCE_NAME` and `INSTANCE_SECRET`), so a rejection usually means those values differ between the platform and Convex services, or the deployment URL is wrong — use `SITE_URL`. Regenerate with `tale convex admin` to be sure you copied the current value. - **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`). ## Where this gets used Once the CLI is wired up, the operator's daily surface shrinks to a handful of subcommands. The pages worth reading next depend on what you came to do — [Upgrades](/self-hosted/operate/upgrades) for version bumps, [Backups and restore](/self-hosted/operate/backups-and-restore) for snapshot drills, [Container architecture](/self-hosted/operate/container-architecture) for what the CLI restarts when it deploys. # Docker Compose reference Source: https://tale.dev/docs/self-hosted/install/docker-compose-reference Tale ships a handful of Docker Compose files. The base is `compose.yml`; the rest are overlays that add or replace services for specific scenarios — development, docs, test. This page names each file, says when to pick it, and gives the layering rule everything else follows. The shape is conservative on purpose. The base file alone runs production; every overlay is opt-in via `-f` and adds only what it needs to. Memorise the base and a single overlay, not the whole grid. ## A worked compose-up A production single-host instance runs from the base alone: ```bash docker compose up -d ``` A developer hacking on platform and docs at the same time layers two overlays: ```bash docker compose -f compose.yml -f compose.dev.yml -f compose.docs.yml up -d ``` The leftmost file is the base; each subsequent file merges its keys on top. Conflicts (same service, same key) resolve last-file-wins. The merged graph is what Docker brings up. ## The compose files | File | Use case | Notable overrides | | ----------------------- | ---------------------------------------------- | --------------------------------------------------------------------- | | `compose.yml` | Production single-host | The base — every service, healthchecks, restart policy | | `compose.dev.yml` | Local development with hot-reload | Mounts source into containers, swaps to dev images, exposes dev ports | | `compose.docs.yml` | Adds the docs site service | Brings up `tale-docs` and routes `/docs` through the proxy | | `compose.web.yml` | Adds the marketing site service | Brings up `tale-web` and routes `/` (root) through the proxy | | `compose.test.yml` | Runs the platform test suite against the stack | Replaces the platform image with the test-shaped variant | | `compose.web.test.yml` | Runs web tests | Like `web.yml` but the test-shaped variant | | `compose.docs.test.yml` | Runs docs tests | Like `docs.yml` but the test-shaped variant | | `compose.test.mock.yml` | Mock-backed integration tests | Swaps providers for mock implementations | ## Services and their roles The base graph brings up eight containers: - `tale-proxy` — Caddy. TLS, reverse proxy, 301s. - `tale-platform` — the TanStack Start app. The user-facing UI and API. - `tale-convex` — the Convex backend. WebSocket, queries, mutations, actions — and the in-process RAG search, document ingestion, web crawling, and document generation that used to be separate services. - `tale-db` — operational Postgres (ParadeDB). The Convex backend's persistent store. - `tale-knowledge-db` — knowledge corpus Postgres (ParadeDB). The `tale_knowledge` database holding document chunks, embeddings, and crawled pages, on port 5433 so it never clashes with `tale-db` on 5432. - `tale-sandbox-llm-gateway` — the LLM gateway for in-sandbox coding agents (pinned external image). - `tale-sandbox-egress` and `tale-sandbox` — the sandbox plane. Run-code containers behind an egress proxy (open by default; lock down with `SANDBOX_EGRESS_ALLOWLIST`), also the headless-browser runtime the convex backend calls for web rendering and document generation. The stack is now entirely TypeScript — there is no Python service in the graph. [Container architecture](/self-hosted/operate/container-architecture) goes deeper on what owns what. ## Overriding Operator customisations belong in an extra overlay, not in edits to the shipped files. Create `compose.local.yml` with the overrides you need: ```yaml services: platform: environment: - LOG_LEVEL=debug ``` Bring the stack up with the local overlay layered last: ```bash docker compose -f compose.yml -f compose.local.yml up -d ``` This pattern keeps `git pull` clean — no merge conflicts on the shipped files. The same pattern works for any custom volume mount, custom port, or environment override. ## Profiles One service in the base file uses a Docker Compose profile. Profiles let a service exist in the graph but not start unless its profile is activated. The profile in use is `controller` — the opt-in `tale-controller` sidecar that restarts the convex container on a signed request so a data-residency change applies without giving the platform Docker-socket access. Activate it with: ```bash docker compose --profile controller up -d ``` ## Where this fits The compose reference is the operator's grid for the source tree. For the inside of each container, the [container architecture](/self-hosted/operate/container-architecture) page covers responsibilities; for the variables the containers read at boot, the [environment reference](/self-hosted/configuration/environment-reference) is the source of truth. # Create the first admin Source: https://tale.dev/docs/self-hosted/install/first-admin A brand-new Tale instance has no users. The first person to open it runs a one-time setup wizard that creates their account, signs them in, makes them the **Owner**, and names the first organization — no bootstrap key, no manual promotion. This walk covers that first run, how teammates join afterward, and where to get the Convex dashboard admin key if you ever need to inspect the backend directly. The one thing to unlearn from older instructions: the first sign-up no longer asks for an admin key. Tale is invite-only after the first account, so there is no open sign-up page to lock down either. ## Before you begin Have the instance running and reachable on `SITE_URL`. Verify with: ```bash docker compose ps ``` Every service should show `running` or `healthy`. If any is unhealthy, [troubleshooting](/self-hosted/operate/observability/troubleshooting) names the four common causes. ## Run the setup wizard Open `SITE_URL`. With no users yet, Tale sends you straight to the setup wizard — there is no separate sign-up page to hunt for, because the log-in screen redirects an empty instance into setup automatically. The wizard creates your account and signs you in mid-flow, then names your first organization. The provider step is optional: skip it and add a key later under **Settings > AI providers**, or connect OpenRouter now to start chatting immediately. Get a key at [openrouter.ai/keys](https://openrouter.ai/keys). The finish step drops you in the dashboard. ## Confirm you're the Owner The first account on a fresh instance is the **Owner** automatically — there is no key to paste and no promotion step. Confirm under **Settings > People** that your row carries the Owner badge. ## How new people join There is no self-service sign-up. Once an Owner exists, `SITE_URL/sign-up` redirects visitors to the log-in page, so nobody can create an account on their own. Add teammates by invite under **Settings > People**; each invite carries the role the new member lands with. The full role model is in [Members and roles](/platform/admin/members-and-roles). ## Get the Convex dashboard admin key The admin key plays no part in the steps above — it only unlocks the **Convex dashboard**, the low-level view of the backend database. The key is deterministic: it is derived from `INSTANCE_SECRET`, so it stays the same across restarts rather than rotating. Get it whichever way fits how you installed: - With the CLI: `tale convex admin` finds the platform container and prints the key. `tale dev` also prints it once services are healthy. - From a git clone: `./scripts/get-admin-key.sh` from the repo root. Open `SITE_URL/convex-dashboard`, enter `SITE_URL` as the deployment URL, and paste the key when prompted. ## Troubleshooting - **The wizard didn't appear — you landed on the log-in page.** Users already exist on this instance; the wizard only runs on a truly empty one. Sign in instead, or have an existing Owner invite you under **Settings > People**. - **A service is unhealthy.** The platform container is not fully up. `docker compose ps` says which service is failing; `docker compose logs platform` shows why. - **The dashboard rejects the admin key.** The key is deterministic from `INSTANCE_SECRET`, so a rejection usually means `INSTANCE_NAME` and `INSTANCE_SECRET` differ between the platform and Convex services, or the deployment URL is wrong — use `SITE_URL`. Regenerate with `tale convex admin` to be sure you copied the current value. ## Where this gets used You now have an Owner and an org, and you know the admin key is a backend-inspection tool, not part of sign-in. The first run is keyless by design: open the URL, the wizard makes you the Owner, and everyone else joins by invite. The next steps that belong on the calendar are inviting the rest of the admins (under **Settings > People**), adding a model provider, and publishing the first agent — the [Cloud onboarding](/cloud/onboarding) walk is identical from this point on except for the URL. # Install Source: https://tale.dev/docs/self-hosted/install Installing Tale has three shapes, and the right one depends on what you are doing with the result. This page routes you to the path that fits — a quick local trial, a production install behind TLS, or the raw Compose reference when you want to own every knob — so you do not start down a hardening walk when you only wanted to click around. All three paths land on the same product; the difference is how much of the stack you operate and how durable the result needs to be. The CLI wraps Docker Compose for the first two so there is nothing to hand-edit, while the reference path is for teams who run Compose themselves. ## Trying Tale on a laptop If you want a running instance to click through — on your own machine, with no domain and no hardening — the [Quickstart](/self-hosted/install/quickstart) is the path. Install the CLI, run `tale init` then `tale dev`, and you are signed into your own org in minutes. The CLI provisions Docker if it is missing, generates every secret, and bind-mounts your config so edits reload live. This is the right path for an evaluation, a demo, or local development against a real stack. When you outgrow the laptop and want the same project on a real host, the trial project carries over — `tale deploy` takes it to a domain without re-initialising. ## Running Tale in production When real traffic will land on the instance, the [Linux server](/self-hosted/install/linux-server) walk is the path. It covers TLS, a firewall, a non-root user, the reverse proxy, and the operational hooks you want before you point a domain at it. The CLI still does the heavy lifting — `tale deploy` runs a blue-green, zero-downtime rollout with health checks and rollback — but this walk adds the host-level setup that a trial skips. After the first deploy, [First admin](/self-hosted/install/first-admin) explains the one-time setup wizard that makes the first account the **Owner** — everyone after that joins by invite, so there is no open sign-up to close — and [CLI install](/self-hosted/install/cli-install) sets up the CLI on a workstation to deploy and upgrade a remote instance. ## Owning the Compose layer If you would rather run the stack from a clone of the repository and manage Compose yourself — for transparency, air-gapped builds, or your own automation — the [Docker Compose reference](/self-hosted/install/docker-compose-reference) is the path. It documents the base file and the overlays the CLI generates under the hood, so you can reproduce or extend them by hand. This is the most control and the most work; most teams are better served by the CLI paths above. This path pairs with the [Linux server](/self-hosted/install/linux-server) walk for the host-level pieces (TLS, firewall, user) that Compose alone does not cover. ## Where this fits The three install paths trade convenience for control: the [Quickstart](/self-hosted/install/quickstart) is the fastest way to a running instance, the [Linux server](/self-hosted/install/linux-server) walk hardens it for real traffic, and the [Docker Compose reference](/self-hosted/install/docker-compose-reference) hands you every knob when the CLI's defaults are not enough. Pick by durability: a trial you will throw away wants the quickstart; an instance your team depends on wants the production walk. Once installed, the [Configuration](/self-hosted/configuration/environment-reference) pages are the source of truth for every environment variable and provider file, and the [Operate](/self-hosted/operate/container-architecture) section covers upgrades, backups, and observability for the running stack. # Production Linux server install Source: https://tale.dev/docs/self-hosted/install/linux-server This walk takes the [quickstart](/self-hosted/install/quickstart) shape and hardens it for production traffic. The result is a single Linux host running Tale behind real TLS, with a firewall, a non-root operator user, and the operational defaults the team should hit before pointing users at the URL. The walk targets a recent Ubuntu LTS or Debian; commands translate one-for-one to RHEL-family distros with `dnf` substituted for `apt`. Skip nothing — the order matters, and each step assumes the previous one landed cleanly. ## Before you begin You need: - A VM or bare-metal host with at least 8 GB RAM, 4 vCPU, and 100 GB disk. Storage grows with attachments and knowledge. - A DNS A record pointing at the host's public IP. Without DNS, Let's Encrypt cannot issue a cert. - Ports 80, 443 reachable from the public internet for TLS issuance; SSH on whatever port your operator policy says. - Sudo on the host. ## Step 1 — Provision the box Update and install the basics: ```bash sudo apt update && sudo apt upgrade -y sudo apt install -y curl git ufw ``` Create a non-root operator user named `tale`: ```bash sudo adduser tale sudo usermod -aG sudo,docker tale ``` Switch to that user (`sudo su - tale`) for the rest of the walk. Operating Tale as root pulls a higher blast radius for no benefit; the rest of the steps assume the `tale` user. ## Step 2 — Install Docker ```bash curl -fsSL https://get.docker.com | sudo sh sudo systemctl enable --now docker ``` Verify with `docker run hello-world`. If the user cannot run docker without sudo, log out and back in to pick up the `docker` group membership. ## Step 3 — Configure firewall and reverse path Allow only what Tale needs: ```bash sudo ufw default deny incoming sudo ufw default allow outgoing sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable ``` If you front Tale with an existing reverse proxy on the same host (rare on a single-host install), set `TLS_MODE=external` in `.env` and adjust the firewall accordingly. The Caddy container inside Tale terminates TLS by default. ## Step 4 — Pull Tale ```bash git clone https://github.com/tale-project/tale.git cd tale cp .env.example .env ``` Set `HOST`, `SITE_URL`, and generate the four secrets as in the [quickstart](/self-hosted/install/quickstart). The production diff versus quickstart lives in step 5 (TLS) and the operational hooks at the end of this walk. ## Step 5 — TLS via Let's Encrypt Open `.env` and set: | Variable | Value | | ----------- | ----------------------- | | `TLS_MODE` | `letsencrypt` | | `TLS_EMAIL` | An ops mailbox you read | Caddy issues and renews the cert automatically using the DNS record from the prerequisites. The first boot waits for the cert; expect a one-minute delay on the first `docker compose up -d` while the ACME challenge runs. ## Step 6 — First boot ```bash docker compose up -d docker compose ps ``` Every service should be `running` or `healthy`. Walk through **Step 4 — Create the first admin** from the [quickstart](/self-hosted/install/quickstart) to land in the dashboard. Open `SITE_URL` over `https://` — the browser should not warn about the cert. ## Step 7 — Operational hooks Before pointing users at the URL, three hooks make life easier later: - **Backups.** Point your existing snapshot tooling at `db-data` and the object store volume — see [Backups and restore](/self-hosted/operate/backups-and-restore). - **Logs.** Tale logs to stdout. If the host has journald, `journalctl -u docker` carries everything; otherwise pipe to your aggregator. - **Metrics.** Set `METRICS_BEARER_TOKEN` in `.env` and scrape `/metrics` from your Prometheus — see [Observability config](/self-hosted/configuration/observability-config). ## Port table | Port | Direction | Purpose | Required | | ---- | --------- | ------------------------------------ | --------------- | | 22 | inbound | SSH | yes, restricted | | 80 | inbound | HTTP, used for ACME and 301 to HTTPS | yes | | 443 | inbound | HTTPS, primary traffic | yes | | 53 | outbound | DNS | yes | | 443 | outbound | model providers, image pulls | yes | ## Troubleshooting - **Let's Encrypt issuance fails.** DNS must resolve to this host's public IP from the public internet, and port 80 must be reachable from the public internet. Run `curl -I http://$HOST` from another machine; if it hits the Caddy challenge, the path works. - **Containers cannot reach model providers.** The host's outbound firewall might block; verify with `docker compose exec platform curl -I https://api.openai.com`. - **TLS cert renews fail later.** Caddy renews 30 days before expiry; failures show in `docker compose logs proxy`. The two common causes are an expired `TLS_EMAIL` mailbox and a DNS change that broke the record. ## Where this gets used You now have a production-shaped install on one host. Two follow-ups belong on the calendar — [Backups and restore](/self-hosted/operate/backups-and-restore) and [Hardening](/self-hosted/operate/security/hardening). If your scale outgrows one host (the rule of thumb is roughly a hundred concurrent users on the recommended spec), the multi-host architecture lives at [Container architecture](/self-hosted/operate/container-architecture). # Self-hosted quickstart Source: https://tale.dev/docs/self-hosted/install/quickstart This is the fastest way to a running Tale: install the `tale` CLI, then two commands. The result is your own org running on your own machine, reachable in the browser. It is meant for a laptop or a single host you want to try Tale on; when you are ready to run it for real, the [Linux server](/self-hosted/install/linux-server) walk covers a hardened production install. ## Before you begin You need nothing to start, and one thing before an agent can answer: - **Docker** — but the CLI provisions it for you: when Docker is missing, `tale dev` offers to install or start it before anything else. If you already run [Docker Desktop](https://www.docker.com/products/docker-desktop) (v24+), or Docker Engine plus the Compose plugin on Linux, the CLI uses that. - An **[OpenRouter API key](https://openrouter.ai)** (or any OpenAI-compatible provider) so agents have a model to talk to. You do not need it for `tale init` — you add it in the app after sign-up, in the setup wizard or under **Settings > AI providers**, and you can swap in any provider later. ## From zero to signed in <Steps> <Step title="Install the CLI"> The installer detects your OS, drops the `tale` binary on your `PATH`, and is the only step that touches your system — it asks for `sudo` when the install directory (default `/usr/local/bin`) is not writable. <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> <Check> `tale --version` printing a version number confirms the binary landed on your `PATH`. </Check> </Step> <Step title="Create a project"> ```bash tale init my-project cd my-project ``` `tale init` scaffolds a project directory, generates every security secret, and writes the `.env`, so there is nothing to hand-edit. The defaults are localhost and a self-signed certificate; the production domain is chosen later, at `tale deploy`. The one question it asks is whether agents may run `docker` / `docker compose` inside their sandboxes — the default is No, because enabling it runs a privileged inner Docker; a single-user install can say yes, while multi-tenant operators should install Sysbox instead. It does not ask for an API key; that is collected in the app once you sign in. It also drops example agents, workflows, integrations, providers, skills, and branding under `default/`, and writes `AGENTS.md` (plus a `CLAUDE.md` pointer) so an AI editor can build configs with full schema awareness. Most of that tree is a catalog rather than live configuration — only entries marked `autoInstall` are active on a new organization, and the generated `default/README.md` explains the split. </Step> <Step title="Start Tale"> ```bash tale dev ``` If Docker is missing, `tale dev` offers to install or start it first. The first run then pulls several gigabytes of images and builds the container graph — the CLI prints per-image pull progress and keeps waiting, so on a slow network this can take tens of minutes. Once the stack reports ready (`Tale is running — open https://localhost`), `tale dev` opens your browser automatically. If it cannot, it prints the URL to visit. <Note> Your browser shows a certificate warning for the local self-signed certificate. That is expected — accept it to continue. </Note> Your config under `default/` is bind-mounted into the running instance, so edits to agents, workflows, and integrations reload live. Stop the stack with `Ctrl-C` (or `tale dev --detach` to run it in the background). </Step> <Step title="Create your account"> On an empty instance there is no sign-up page to hunt for: the first visit lands in the one-time setup wizard, which creates your account, signs you in, makes you the **Owner**, and names your **Organization**. You land in the dashboard — no admin key involved, and nothing to lock down afterward, because everyone after you joins by invite. <Note> [First admin](/self-hosted/install/first-admin) covers the wizard in detail, how teammates join, and the Convex dashboard admin key — a backend-inspection tool that plays no part in sign-in. </Note> </Step> <Step title="Add a model and publish an agent"> You now have an empty org. Two moves get you to something useful: add your OpenRouter key — the setup wizard prompts for it right after you create the owner account, and **Settings > AI providers** takes it any time later — then publish your first agent with [Create an agent](/platform/agents/create). A confirmation on the provider row means the key works. <Check> A new chat answering a message is the end-to-end proof: provider, model, and agent all work. From here the [Platform](/platform) docs are the canonical reference for every feature, identical to Cloud. </Check> </Step> </Steps> ## Prefer raw Docker Compose? The CLI wraps `docker compose` so you do not have to. If you would rather run the stack from a clone of the repository and manage compose yourself — for transparency, air-gapped builds, or your own automation — clone the repo, copy `.env.example` to `.env`, set `HOST` and `SITE_URL`, generate the secrets, and `docker compose up -d`. The [Linux server](/self-hosted/install/linux-server) walk and the [Docker Compose reference](/self-hosted/install/docker-compose-reference) cover that path end to end. ## Troubleshooting - **`tale` not found after install.** The installer names the destination directory in its output; make sure that directory is on your `PATH` (on Linux it is usually `/usr/local/bin`). - **`tale dev` exits with a port conflict.** Read the compose error to see which port is taken. If it is 443, another service binds HTTPS on the host — free it, or remap with `tale dev --port 8443` (the flag remaps only the HTTPS port). The sandbox spawner always binds `127.0.0.1:8003` and cannot be remapped, so two Tale dev projects cannot run on one machine at the same time. - **Docker is not running.** `tale dev` offers to start (or install) it — accept the prompt, or start Docker Desktop yourself (`sudo systemctl start docker` on Linux) and retry. - **A container crash-loops on first boot.** Almost always a missing secret — re-run `tale dev`, which re-runs environment setup, or inspect logs with `tale logs platform`. ## Where this gets used You now have a working Tale instance on your machine. To run it for real, the [Linux server](/self-hosted/install/linux-server) walk covers TLS, firewall, a non-root user, and the operational hooks you want before real traffic lands; [CLI install](/self-hosted/install/cli-install) sets the CLI up to deploy and upgrade a remote instance from your workstation. # Backups and restore Source: https://tale.dev/docs/self-hosted/operate/backups-and-restore Tale's backup unit is the volume snapshot: a paused, checksummed tar of every data volume in the instance, written into a dedicated `backups` volume that lives next to the data it protects. The CLI takes one automatically before any deploy step that can migrate data, and `tale backup` takes one on demand. Recovery is `tale restore <snapshot-id>` plus a redeploy of the matching version — that pair is the answer to a failed upgrade, and the reason `tale rollback` can afford to refuse anything beyond a patch step. The architecture context lives in [Container architecture](/self-hosted/operate/container-architecture); this page covers what a snapshot contains, when one is taken, how the copy gets off the host, and the restore walk. ## What a snapshot contains | Volume | Holds | | ---------------------------- | ----------------------------------------------- | | `db-data` | Postgres — agents, runs, the audit log | | `convex-data` | Org config, provider secrets, uploaded branding | | `rag-data` | The vector index built from your documents | | `crawler-data` | Crawled website knowledge | | `caddy-data`, `caddy-config` | TLS certificates and proxy state | Each snapshot is a directory named like `20260611-142530-deploy` inside the project's `backups` volume: one `.tar.gz` per volume, a `.sha256` sidecar each, and a `manifest.json` written last. A directory without a manifest is an incomplete snapshot — it never shows up in listings and can never be restored. Two things live outside the volumes and need separate capture: the project workspace (the directory holding `tale.json`) and `.env`. ## When snapshots are taken `tale deploy` snapshots before its first mutating step whenever the deploy can change data: the target version differs from the running one, or a host-config push (`--override` / `--override-all`) is requested. While each volume is tarred, the containers using it are paused for a few seconds so the archive is crash-consistent — a live copy of a running Postgres directory is not restorable. A failed snapshot aborts the deploy. `--skip-backup` overrides that on `tale deploy`, which leaves your own external backups as the only recovery path — the flag logs a loud warning for exactly that reason. ```bash # Take a snapshot right now tale backup ``` ## Retention Rotation keeps the newest five snapshots and everything from the last 14 days — whichever is more generous. A snapshot is deleted only when it is both beyond the count window and older than the age window, so a quiet instance keeps its last snapshots indefinitely. Override the windows with `BACKUP_KEEP_COUNT` and `BACKUP_KEEP_DAYS` in `.env`. ## Off-host copy The snapshots live on the same host as the data they protect — a dead disk takes both. Point your existing backup tooling (Restic, Borg, Velero, cloud-provider snapshots) at the `backups` volume, and capture the project workspace and `.env` in the same job. Tale does not ship an upload step — keeping the off-host copy under your existing backup contract is deliberate. ```bash # crontab on the host — hourly Restic copy of the backups volume to S3 0 * * * * restic -r s3:s3.amazonaws.com/bucket/tale backup \ /var/lib/docker/volumes/<project-id>_backups/_data ``` Find the volume's host path with `docker volume inspect <project-id>_backups`; the project id lives in `tale.json`. ## Restoring a snapshot `tale restore` without arguments lists what is available; with an id it verifies the checksums, wipes the data volumes, and extracts the snapshot. It refuses while any project container runs — pass `--stop` to stop them — and asks for confirmation before touching anything. ```bash # See what's available tale restore # Stop the stack and restore tale restore 20260611-142530-deploy --stop # Bring the stack back on the version that matches the data tale update --version 0.9.6 tale deploy --stop ``` The redeploy of the matching version is part of the restore, not an optional extra: the snapshot captured the data exactly as that platform version left it, and a newer binary would immediately re-run its migrations against it. The restore output prints the exact version recorded in the snapshot's manifest. ## Restore drill Run the drill quarterly on a non-production host. The drill is not "does a snapshot exist" — it is "can a fresh host be rebuilt from the off-host copy of the `backups` volume, the project workspace, and `.env` in under an hour." The failure modes the drill catches: an off-host job that never captured the workspace, and a stale `.env` that no longer matches the current binary's requirements. ## Where this fits Snapshots are the cheap part; the restore drill is what proves they work, and the redeploy-the-matching-version rule is the one thing to remember — recovery is never "roll the binary back," it is "restore the data and deploy the version it belongs to." The upgrade flow these snapshots protect lives in [Upgrades](/self-hosted/operate/upgrades); the hardening checklist that names backups as a row is in [Hardening](/self-hosted/operate/security/hardening). # Container architecture Source: https://tale.dev/docs/self-hosted/operate/container-architecture A Tale instance is eight containers wired by docker compose. The architecture page covered what each container is for; this page is the operator's version — which container owns which job, how a chat message flows through them, and what the failure mode looks like when one of them dies. Read this when you are on call. Come back when you are deciding which container to roll first during an upgrade. ## The eight containers, with their jobs | Container | Job | Crashes affect | | -------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | `tale-proxy` | TLS termination + edge routing | All ingress — no client can reach the UI | | `tale-platform` | UI server, static asset delivery | Browser sees 502; the API is still reachable | | `tale-convex` | Backend actions/queries/mutations + WebSocket, plus in-process RAG, crawling, and document gen | UI loads, but no data; in-flight chats stall; ingestion stalls | | `tale-db` | Operational Postgres for Convex | Convex falls back to read-only; writes block | | `tale-knowledge-db` | Knowledge corpus Postgres (document chunks, embeddings, crawled pages) | Knowledge search returns empty; ingestion fails | | `tale-sandbox-llm-gateway` | LLM gateway for in-sandbox coding agents | Sandboxed agents can't reach a model; chat is unaffected | | `tale-sandbox-egress` | Network egress for sandboxed code | `Run code` tool errors with "egress denied"; web render fails | | `tale-sandbox` | Sandbox runtime + headless browser for web render and document generation | `Run code`, web crawl render, and document generation all fail | One container is exposed to the public network (`tale-proxy` for HTTPS, and optionally `tale-sandbox-egress` outbound for the sandbox); the rest are internal-only. The opt-in `tale-controller` sidecar (the `controller` profile) is off by default; when enabled it restarts `tale-convex` on a signed request so a data-residency change can apply without handing the platform Docker access. ## The request path A chat message takes one round trip through the containers: 1. Browser → `tale-proxy` (TLS terminated). 2. `tale-proxy` → `tale-platform` for HTML/JS, → `tale-convex` for API + WebSocket. 3. `tale-convex` reads the org's provider config, picks the model, opens a stream to the upstream provider. 4. If the agent retrieves knowledge: `tale-convex` runs the RAG search in-process, querying `tale-knowledge-db` directly — no separate retrieval service in the path. 5. If the agent runs code: `tale-convex` → `tale-sandbox` → `tale-sandbox-egress` for any outbound network. 6. The provider stream tokens back through `tale-convex` to the browser over the WebSocket. The hot path is short. If chat latency feels wrong, the container to blame is almost always the upstream provider, not Tale; the metrics endpoints on `tale-convex` (which now carries the RAG and crawl timings as well) surface the time spent in each hop. ## The sandbox plane Sandboxed code execution runs in `tale-sandbox` with `tale-sandbox-egress` as the only network seam. The two-container split is deliberate: `tale-sandbox` itself has no outbound network; every request the sandboxed code makes goes through `tale-sandbox-egress`, which blocks cloud-metadata and private-range targets at the IP layer and — when the operator sets `SANDBOX_EGRESS_ALLOWLIST` — enforces a default-deny hostname allowlist on top. If the egress container is down, sandboxed code that needs the network fails closed with "egress denied" — not a silent timeout. The sandbox runtime carries Chromium and Playwright, so the convex backend reuses it for the headless work it cannot do in-process: rendering a JavaScript page during a web crawl, and turning generated HTML into a PDF or image. Those jobs run as ephemeral sandbox executions rather than user code, but they ride the same egress and isolation seam. The sandbox is the only container that runs untrusted-ish code (user-supplied skill scripts, agent `Run code` invocations); the rest of the stack runs the platform's own code. ## Failure modes — what each container's outage looks like **`tale-proxy` down.** TLS handshake fails; every client sees a connection error. Inside the host, the platform and convex containers are still up — restart proxy first. **`tale-platform` down.** Browser gets 502 from proxy; the API keeps working. Existing browser tabs with cached assets continue to talk to convex over the WebSocket and may not notice until they reload. **`tale-convex` down.** Browser loads the UI shell but nothing populates. WebSocket reconnects loop. Restarting convex is safe — sessions are server-side; clients re-subscribe on reconnect. **`tale-db` down.** Convex enters its degraded mode: reads from cache, writes are queued. Long outages eventually surface as "saving failed" toasts. **`tale-knowledge-db` down.** Document ingestion fails and knowledge search returns empty — agents that retrieve knowledge get an empty result set and a warning in the execution log. The rest of the app keeps working; chats without knowledge are unaffected. Restarting the container clears it, and in-flight uploads retry on the next pass. **`tale-sandbox` / `tale-sandbox-egress` down.** `Run code` tool calls return an error and skill scripts fail. Because the convex backend renders web pages and generates documents through the sandbox runtime, a web crawl that needs JavaScript rendering and document generation also fail closed while the sandbox is down. Agents that use none of these keep working. **`tale-sandbox-llm-gateway` down.** In-sandbox coding agents lose their path to a model provider. Regular chat — which calls providers directly from convex, not through the LLM gateway — is unaffected. ## Where this fits This page is the operator's map; the [Architecture overview](/self-hosted/overview) is the introduction to the same picture, the [Troubleshooting](/self-hosted/operate/observability/troubleshooting) page is the symptom-first index when something has gone wrong. If you are setting alert thresholds, [Operations](/self-hosted/operate/observability/operations) names the signals worth wiring. # Operations Source: https://tale.dev/docs/self-hosted/operate/observability/operations The operations page is the alert playbook — which signals are worth waking someone for, which can ride out a coffee, and what the first five minutes of an incident look like. Tale's metrics surface lives behind `METRICS_BEARER_TOKEN`; this page assumes you have wired up Prometheus and Grafana per [Observability config](/self-hosted/configuration/observability-config) and now need to know which numbers to watch. The symptom-first index is at [Troubleshooting](/self-hosted/operate/observability/troubleshooting). This page is the proactive side — signals first, oncall checklist second. ## Signals worth alerting on | Signal | Severity | Why it matters | | ------------------------------------------- | -------- | --------------------------------------------------- | | `tale-proxy` health probe failing > 1 min | page | Every user sees a connection error | | `tale-platform` HTTP 5xx rate > 5 % | page | The UI is broken for a meaningful share of requests | | `tale-convex` WebSocket reconnect storm | page | UI loads but no data flows | | Postgres connections > 80 % of pool | warn | The next spike will start blocking | | `db-data` volume > 80 % full | warn | The operational Postgres goes read-only at full | | `knowledge-db-data` volume > 80 % full | warn | Ingestion fails when the corpus database is full | | `tale-knowledge-db` unreachable from convex | warn | Knowledge search returns empty; ingestion stalls | | Provider request error rate > 20 % | warn | The upstream LLM provider is having a bad day | | Daily backup did not write | page | Restore drill will fail at the worst moment | | TLS cert renewal failed | warn | Renews 30 d before expiry — you have time | The first two pages are the actually-customer-impacting ones. The warns are catching trends before they tip into page territory. ## Log signals to grep for Logs come through stdout per container, captured by Docker's `json-file` driver. The four phrases that consistently mean trouble: - `panic` or `unexpected error` in `tale-convex` logs — Convex action crash. - `decryption failed` in `tale-platform` logs — SOPS age key mismatch with the file on disk. - `429 Too Many Requests` repeated from a provider — rate limit hit, agents will start failing. - `connection refused` or `ECONNREFUSED` to `knowledge-db` in `tale-convex` logs — the backend cannot reach the corpus database; ingestion and knowledge search fail. Pipe these to your aggregator as derived alerts; the metrics endpoints do not surface them as gauges. ## Oncall checklist When a page lands, the first five minutes follow the same shape every time. 1. **Confirm the alert is real.** Open `$SITE_URL` in a browser. If the UI loads and chat works, you are looking at a metrics or scraper issue, not a customer-impacting one. 2. **Identify the container.** `docker compose ps` shows which is unhealthy; `docker compose logs --tail=200 <service>` shows the last error. 3. **Restart the most-likely culprit.** `docker compose restart <service>` resolves a surprising fraction of incidents — process crashes, file watchers gone stale, exhausted connection pools. The architecture is built to survive a single container restart cleanly. 4. **Check upstream providers.** `https://status.openai.com`, `https://status.anthropic.com`, etc. If the provider is on fire, agents fail; Tale is not the cause. 5. **Page the on-call engineer if the user-visible symptom persists after a restart.** No need to escalate sooner — most incidents resolve in the first three steps. ## What does not need oncall A `tale-knowledge-db` outage is a warn, not a page. The web-crawl schedule absorbs hours of downtime without user impact, and document ingestion retries rather than dropping work — uploads sit in "indexing" until the corpus database is back. Knowledge search returns empty in the meantime, but chats that do not retrieve knowledge keep working. Catch this in the warn band and fix it in business hours. ## Response-time SLAs Two response-time budgets are tracked as first-class signals: interactive dialog input and long-running operations such as evaluations. Both are verified as a **mean** over a rolling window — the contractual figure is an average, not a per-request ceiling — and both are wired so Prometheus alerts the moment the average drifts past budget. | Budget | Statistic | Target | Window | Underlying series | | -------------- | --------- | ------ | ------ | ----------------------------- | | Dialog input | mean | ~1 s | 30 m | `tale_dialog_ttft_seconds` | | Long operation | mean | ~40 s | 6 h | `tale_long_operation_seconds` | Each target also rides the platform metrics endpoint as `tale_sla_target_seconds{sla,statistic}`, so a Grafana panel draws the budget line straight from Prometheus instead of hard-coding it. The underlying latency series are the Convex function-execution histograms on `/metrics/convex`; relabel or record them to the names above so the rules resolve. The platform serves the ready-made recording and alerting rules at `/metrics/sla-rules` (behind the same bearer token as the other metrics paths) — fetch it once and reference the file under `rule_files:`, or paste the equivalent: ```yaml groups: - name: tale-sla-recording rules: - record: tale_sla_dialog_ttft:mean30m expr: rate(tale_dialog_ttft_seconds_sum[30m]) / rate(tale_dialog_ttft_seconds_count[30m]) labels: sla: dialog_ttft - record: tale_sla_long_operation:mean6h expr: rate(tale_long_operation_seconds_sum[6h]) / rate(tale_long_operation_seconds_count[6h]) labels: sla: long_operation - name: tale-sla-alerts rules: - alert: TaleSlaDialogTtftBreached expr: tale_sla_dialog_ttft:mean30m > 1 for: 15m labels: severity: warn sla: dialog_ttft annotations: summary: 'Dialog input response time: mean response time over 30m exceeds the 1s SLA' description: Mean time-to-first-token for an interactive chat / dialog turn. - alert: TaleSlaLongOperationBreached expr: tale_sla_long_operation:mean6h > 40 for: 30m labels: severity: warn sla: long_operation annotations: summary: 'Long operation response time: mean response time over 6h exceeds the 40s SLA' description: Mean end-to-end time for long-running operations such as evaluations. ``` A breach here is a **warn**, not a page: a drifting average is a degradation to chase in business hours, and the `for:` windows deliberately wait out a short spike before firing. The ~1 s dialog budget reconciles with the looser ~3 s warm time-to-first-token in the manual performance plan — that ~3 s is a per-request ceiling for a single cold, Auto-routed first token including model and network time, whereas the ~1 s here is the steady-state mean across dialog turns, so occasional first tokens reaching the ceiling are consistent with a sub-second mean. Holding the 1 s mean on live providers may still need the backend-overhead optimization tracked on the feature issue; this alert is what confirms whether the target is met. ## Where this fits The signals above are the proactive side of operating a Tale instance; the reactive side is [Troubleshooting](/self-hosted/operate/observability/troubleshooting), and the configuration that gets the metrics into Prometheus is [Observability config](/self-hosted/configuration/observability-config). If you have not yet set `METRICS_BEARER_TOKEN`, every threshold above is unmonitored — start there. # Prometheus and Grafana Source: https://tale.dev/docs/self-hosted/operate/observability/prometheus-grafana This is the worked example behind [Observability config](/self-hosted/configuration/observability-config): a Prometheus and Grafana pair you can drop next to Tale, pointed at the two bearer-token metrics endpoints, with a starter dashboard and one alert rule to build on. It's for self-hosted operators who have already set `METRICS_BEARER_TOKEN` and now want live graphs instead of a `curl` against `/metrics`. The config-reference page lists the endpoints and the single scrape stanza; this page stands the whole stack up end to end. Everything here runs on the same host as Tale, so no metric leaves the box. ## Before you start Set `METRICS_BEARER_TOKEN` in your `.env` and restart the proxy — without it the two endpoints return 401 to every request, and Prometheus will show each target as down. The endpoints, and what each one carries, are the table in [Observability config](/self-hosted/configuration/observability-config#metrics): `/metrics/platform` and `/metrics/convex` (the latter now carries the in-process RAG and crawl timings), both served by `tale-proxy` over the same hostname as the app. ## Add Prometheus and Grafana to your stack Drop these two services into a compose override next to Tale. Prometheus scrapes on an interval and stores a local TSDB; Grafana reads Prometheus and renders the dashboards. Both bind to localhost only — reach Grafana through an SSH tunnel or put it behind the same proxy with auth, never expose it raw. ```yaml # docker-compose.metrics.yml — start with: docker compose -f docker-compose.yml -f docker-compose.metrics.yml up -d services: prometheus: image: prom/prometheus:v3.1.0 volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro - prometheus-data:/prometheus ports: - '127.0.0.1:9090:9090' restart: unless-stopped grafana: image: grafana/grafana:11.4.0 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 volumes: prometheus-data: grafana-data: ``` ## Scrape configuration Tale's two endpoints share one bearer token, so the scrape config is the published stanza repeated once per path. Save this as `prometheus.yml` next to the override above and substitute your host and token — Prometheus reads the token from the file, so keep it `chmod 600` and out of version control. ```yaml global: scrape_interval: 30s scrape_configs: - job_name: tale-platform scheme: https metrics_path: /metrics/platform authorization: { credentials: '${METRICS_BEARER_TOKEN}' } static_configs: - targets: ['tale.example.com'] - job_name: tale-convex scheme: https metrics_path: /metrics/convex authorization: { credentials: '${METRICS_BEARER_TOKEN}' } static_configs: - targets: ['tale.example.com'] ``` Open `http://127.0.0.1:9090/targets` after start — both jobs should read **UP**. A target stuck **DOWN** with a 401 means the token in `prometheus.yml` does not match `METRICS_BEARER_TOKEN`; a connection error means the hostname or scheme is wrong. ## A starter dashboard Point Grafana at Prometheus first — add a Prometheus data source at `http://prometheus:9090` (Grafana reaches it by the compose service name). Then build a dashboard from these panels; the first three use metrics that are always present, and the rest map to the signals in [Operations](/self-hosted/operate/observability/operations). | Panel | Query | Reads as | | --------------- | ---------------------------------------------------- | ------------------------------------------------- | | Targets up | `up{job=~"tale-.*"}` | `1` per healthy endpoint, `0` when scraping fails | | Platform memory | `process_resident_memory_bytes{job="tale-platform"}` | Resident memory of the platform container | | Event-loop lag | `nodejs_eventloop_lag_seconds{job="tale-platform"}` | Spikes when the platform is saturated | | Convex up | `up{job="tale-convex"}` | Backend reachability — `0` is a page | The platform endpoint carries Node's default process metrics (CPU, memory, event-loop lag, GC), which is why the concrete queries above target it. The Convex endpoint exposes its own richer series, including the in-process RAG and crawl timings — open it once (`curl -H "Authorization: Bearer $TOKEN" https://tale.example.com/metrics/convex`) to read the exact metric names your version exposes, then add panels for knowledge-ingestion throughput and provider error rate called out in Operations. ## A first alert rule Start with the one signal that is unambiguous — a metrics target that stops responding. Add this rule file to Prometheus (mount it and reference it under `rule_files:` in `prometheus.yml`), then wire Alertmanager or Grafana alerting to your pager. ```yaml 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' ``` The full list of what's worth paging on versus what can wait — platform 5xx rate, Postgres pool saturation, knowledge-database reachability, daily-backup-did-not-write — is the signal table in [Operations](/self-hosted/operate/observability/operations); translate each row into a rule once the matching series is on your dashboard. ## Where this fits This page turns the two documented metrics endpoints into a running Prometheus and Grafana stack: a compose override, a two-job scrape config, a starter dashboard, and a target-down alert you extend with the Operations thresholds. Keep both services bound to localhost and the bearer token off disk-in-the-clear, and the whole monitoring surface stays on the host with Tale. The endpoints and the token that gate them are owned by [Observability config](/self-hosted/configuration/observability-config); the thresholds and the oncall checklist are [Operations](/self-hosted/operate/observability/operations). When a panel goes red, the symptom-to-fix lookup is [Troubleshooting](/self-hosted/operate/observability/troubleshooting). # Troubleshooting Source: https://tale.dev/docs/self-hosted/operate/observability/troubleshooting This page is the symptom-first lookup when something is wrong right now. Each section starts with what the user actually reports — what the browser shows, what the agent fails on, what the upload screen says — and walks back to the cause and the fix. Anything not listed here is a candidate for a new section once it has shown up twice. The proactive side — signals worth alerting on, what to wire into Prometheus — lives in [Operations](/self-hosted/operate/observability/operations). This page is for the moment after the page fired. ## Browser sees 502 or "Bad Gateway" The `tale-proxy` container reached the platform, but the platform did not reply. Either `tale-platform` is down or its health endpoint is unreachable. Check container state first: ```bash docker compose ps tale-platform docker compose logs --tail=200 tale-platform ``` If the container is restarting, the logs at the bottom show the crash reason — usually a misconfigured env var (`SITE_URL` mismatch, missing `BETTER_AUTH_SECRET`) or a Postgres connection failure. Fix the env, restart, retry. If the container is healthy but the browser still sees 502, the proxy is the suspect — `docker compose restart tale-proxy` clears most of these. ## Browser sees a TLS warning `TLS_MODE=selfsigned` is the most common cause — the browser does not trust Caddy's internal CA on first visit. Either trust the CA on the host (`docker exec tale-proxy caddy trust`) or switch to `TLS_MODE=letsencrypt` for a real certificate. The full mode walk lives in [TLS and domains](/self-hosted/configuration/tls-and-domains). If the mode is already `letsencrypt`, check the proxy logs for ACME failures — DNS not resolving to this host's public IP and port 80 unreachable from the public Internet are the two common causes. ## UI loads but no data appears The UI shell is static assets served by `tale-platform`; everything else flows through `tale-convex` over a WebSocket. When the WebSocket cannot connect, the shell loads and stays empty. Symptoms: spinners that never resolve, "reconnecting" toasts, the chat input that never accepts a message. ```bash docker compose logs --tail=200 tale-convex ``` The convex container is probably restarting (look for `panic` in the logs) or unreachable from the proxy. Restart with `docker compose restart tale-convex` — sessions are server-side and clients re-subscribe on reconnect, so the restart is safe. ## Uploads stuck in "indexing" Document ingestion runs inside the Convex backend and writes the extracted chunks and embeddings to the knowledge corpus database. A long "indexing" state means either the backend cannot reach `tale-knowledge-db` or the file itself failed to extract. Check the convex logs and the corpus database first: ```bash docker compose logs --tail=200 tale-convex | grep -iE "knowledge|ingest|embed" docker compose ps tale-knowledge-db ``` If the logs show connection errors to `knowledge-db`, restart the corpus database (`docker compose restart tale-knowledge-db`); ingestion retries on the next pass, so uploads do not have to be re-submitted. If the database is healthy but a specific upload is stuck, the file itself is the suspect — corrupt PDFs and password-protected documents land in a failure state and require deletion and re-upload. ## Chat replies stop mid-stream The token stream from the upstream provider dropped — either the provider rate-limited, the connection timed out, or the provider's service is degraded. Check the provider's status page first; then look in the platform logs: ```bash docker compose logs --tail=200 tale-platform | grep -E "429|503|stream" ``` A `429` is the common case. Either the org's budget is hitting the provider's rate limit, or the provider key itself is throttled. Switching the org's default model to a less-loaded provider clears the symptom while the upstream cools off. ## Saving fails with "saving failed" toast The convex container could not write to Postgres. Either `tale-db` is down or its disk is full: ```bash docker compose ps tale-db docker compose exec db df -h /var/lib/postgresql/data ``` A disk at 100 % is the failure that produces the most surprised faces. Free space, restart `tale-db`, and the queued writes flush. If the disk has room, the suspect is connection-pool exhaustion or a lock — restart `tale-convex` to clear the pool. ## "Run code" tool errors with "egress denied" The `tale-sandbox-egress` container is the only outbound network path for sandboxed code; if it is down or misconfigured, every outbound request from the sandbox fails closed. Check the egress container first: ```bash docker compose ps tale-sandbox-egress docker compose logs --tail=100 tale-sandbox-egress ``` If the container is healthy and you have set `SANDBOX_EGRESS_ALLOWLIST`, the request hit the allowlist — extend the variable in `.env` and recreate `tale-sandbox-egress`. Without an allowlist the proxy is open at the hostname layer, so check the target instead: only port 443 is tunnelled for HTTPS, and cloud-metadata and private-range addresses are always blocked at the IP layer. ## Sign-in loops back to the sign-in screen `SITE_URL` does not match what the browser actually requested. Auth cookies are scoped to the URL the request landed on; a mismatch (trailing slash, missing port, `http` vs `https`, base-path prefix) means the cookie set on the callback does not get sent on the next request. Fix `.env`: ```bash SITE_URL=https://tale.example.com # exactly what the user types ``` Recreate the platform container (`docker compose up -d --force-recreate tale-platform`) for the change to land in the rendered HTML. ## Where to get help Self-hosted instances do not phone home, so support starts with you. The two channels: - **GitHub Issues** — bugs and reproducible problems. The [tale-project/tale](https://github.com/tale-project/tale/issues) tracker has a template that asks for the diagnostics bundle `tale diagnostics` produces. - **Discord** — questions, configuration debates, "is this a bug" triage. The invite lives in the repo README. Reproducible diagnostics make every channel faster. `tale diagnostics` collects sanitised logs, env vars (secrets redacted), and container health into a single archive worth attaching. # How to read release notes Source: https://tale.dev/docs/self-hosted/operate/release-notes/format Tale ships a release per minor version and patches as bug-fix tags between them. The release notes for every tag follow the same shape so you can scan one in a minute and know whether the upgrade is a five-minute bump or a maintenance window. This page covers the format: the semver promise, what each section guarantees, and where to read deeper when a row points at a migration. The notes themselves live on the GitHub release page for each tag. The CLI also surfaces them — `tale update --notes` prints the notes for the version it is about to install. ## The semver promise Tale versions are semver, and the version number is the headline fact about an upgrade. - **Patch (`0.9.0 → 0.9.1`)** — bug fixes only. No schema migrations, no config changes, no behaviour changes other than the fix itself. Safe to upgrade without reading past the security section. - **Minor (`0.9.x → 0.10.x`)** — new features, possibly forward-only migrations. Backwards-compatible by default; deprecations are announced one minor in advance. - **Major (`0.x → 1.x`)** — breaking changes are allowed. Always carries a migration-notes link at the top of the release; read it end-to-end before starting. The version line at the top of every release page names the bump kind in plain English so you do not have to do the arithmetic yourself. ## The sections every release has Each release page is the same ordered list of sections. Empty sections are omitted, not left blank — if you do not see a section, there is nothing to report there. - **Highlights** — one or two paragraphs naming what the release is for. Read this first. - **Breaking changes** — every change that requires the operator to do something before or after the upgrade. Each row names the symptom you would hit if you skipped, and the action that avoids it. - **Deprecations** — features still working in this release but flagged for removal. Each row names the removal version so you can plan the cutover. - **Security** — CVE-format entries for fixes that close a vulnerability. The full feed lives under [Security advisories](/self-hosted/operate/security/advisories); the release notes carry the one-line summary plus the advisory link. - **Features and fixes** — the long list. Grouped by area (Platform, CLI, Docs); each row reads as one sentence. - **Migration notes** _(major versions and some minors)_ — the linked walk through schema migrations, config-file changes, or operator-facing renames. Always read for majors. ## How to scan a release Read the version line, the highlights, and the breaking-changes section. If breaking changes is empty and the security section does not name a fix that touches your install, the upgrade is the `tale update` + `tale deploy` sequence from [Upgrades](/self-hosted/operate/upgrades). If either section has rows, walk them before running `tale deploy`. ```text 0.12.0 (minor) — 2026-05-14 Highlights Streaming tool calls now stream into the chat as they emit. Breaking changes (none) Deprecations AGENTS_LEGACY_PROMPT env var — removed in 0.14. Security CVE-2026-XXXX — patched bypass in the run-code sandbox. See: advisory TAL-2026-007. ``` The shape above is what `tale update --notes` prints. The web version of the same release adds links on every advisory and migration row. ## Where this fits The release-notes format is the contract between the project and the operator — the same shape every release so the upgrade decision is a scan, not a deep read. The natural next steps are [Upgrades](/self-hosted/operate/upgrades) for the deploy mechanics and [Security advisories](/self-hosted/operate/security/advisories) for the long-form vulnerability feed the security section links into. # Security advisories Source: https://tale.dev/docs/self-hosted/operate/security/advisories Tale publishes a security advisory for every vulnerability that closes through a patched release. The feed lives on GitHub Security Advisories under the `tale-project/tale` repository and mirrors to an RSS endpoint operators can wire into their alerting. This page covers the format every advisory follows, the severity scale Tale uses, the disclosure timeline maintainers commit to, and the three subscription paths. The advisories are the long-form record. The one-line summary plus a link appears in the **Security** section of each [release note](/self-hosted/operate/release-notes/format). ## The advisory format Every advisory is a GitHub Security Advisory with a stable identifier of the form `TAL-YYYY-NNN` (Tale's internal id) plus the upstream `CVE-YYYY-NNNNN` if one was assigned. The body is the same ordered set of sections so an operator can scan the load-bearing facts without reading the prose. - **Summary** — one sentence naming what an attacker could do and what the fix changes. - **Affected versions** — the version range that contains the vulnerability, in semver form (`>=0.8.0, <0.12.3`). - **Patched versions** — the first release that contains the fix. Upgrading to or past this version closes the vulnerability. - **Severity** — one of the four tiers below, plus the CVSS 3.1 vector for operators who score against their own threat model. - **Workarounds** — what to set, disable, or block to mitigate the vulnerability when an immediate upgrade is not possible. Empty when no workaround exists. - **Credits** — the reporter, when they have asked to be named. The patched-version row is the one most operators land on first; the upgrade itself is the two-command sequence from [Upgrades](/self-hosted/operate/upgrades). ## The severity scale Tale uses four tiers. The tier is set from the CVSS score and the reachability of the vulnerable surface on a default install. | Tier | CVSS | What it means | | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | | Critical | 9.0+ | Pre-authenticated remote code execution or unauthenticated data exfiltration. Patch within 24 hours. | | High | 7.0–8.9 | Authenticated escalation, sandbox escape, or cross-tenant data leak. Patch within a week. | | Moderate | 4.0–6.9 | Information disclosure, denial of service, or escalation requiring rare preconditions. Patch on the next maintenance window. | | Low | 0.1–3.9 | Defence-in-depth fixes and hardening without a known exploit path. Patch when convenient. | The CVSS vector lets you re-score against your own deployment — an advisory rated High against a public install may be Low against an air-gapped one. ## The disclosure timeline Maintainers commit to the following timeline from the moment a report lands at `security@tale.dev`: - **Within 72 hours** — acknowledgement, a triage call, and a TAL identifier assigned. - **Within 14 days** — a fix or a workaround published privately to the reporter, and the patched version planned. - **At fix release** — the advisory publishes on GitHub, the CVE assignment is requested, and the security section of the release notes carries the summary. - **30 days after release** — the technical detail in the advisory expands with the reproducer (when reproducing in public no longer puts unpatched installs at risk). Reporters can request a delay if they need more time to disclose; maintainers accept up to 90 days before publishing the summary anyway. On the engineering side, dependency fixes move on a fast track so the patched release lands quickly: Renovate opens a security update PR within 24 hours of an upstream advisory — bypassing the normal release-age delay that applies to routine updates — and CI blocks any merge that introduces a known high or critical advisory. A disclosed dependency CVE therefore turns into a patched Tale release in days, not on the next routine cadence. ## Subscribing Three paths to the same feed: ```text GitHub watch — github.com/tale-project/tale → Watch → Custom → Security alerts RSS — https://github.com/tale-project/tale/security/advisories.atom Email digest — security-announce@tale.dev (one mail per advisory, no traffic between) ``` The RSS feed is what most operators wire into Slack or PagerDuty; the email digest is for one-person teams that do not run an alerting pipeline. ## Where this fits The advisory feed is one of the two contracts that make Tale safe to self-host — release notes name what changes, advisories name what was wrong. The natural next reads are [How to read release notes](/self-hosted/operate/release-notes/format) for the matching change-log format and [Hardening](/self-hosted/operate/security/hardening) for the checklist that limits exposure before an advisory ever fires. # Audit-log integrity alerts Source: https://tale.dev/docs/self-hosted/operate/security/audit-log-integrity Tale verifies every organisation's audit-log hash chain on a schedule and raises an alert the moment a verification fails. This page is the runbook for the operator or admin who received that alert: how to read the finding, how to separate a genuine tamper signal from an ordinary retention or configuration artifact, and what to preserve before you touch anything. The alert is deliberately loud because a real break is rare and serious — but most breaks that fire in practice have an everyday explanation, so the work is to rule those out methodically rather than to panic. ## What triggers it A daily cron walks every organisation's append-only audit chain along with its retention and scrub checkpoints. When a chain fails to verify, the run does two things. It writes an in-band `security` audit row — on every failing run, so the durable record is always complete — and it raises an out-of-band notification to the organisation's admins, in the notification bell and in your Slack channel when one is connected. The out-of-band alert is deduplicated. You get one notification when a break is first detected, and one more only if it changes — a different broken row, or a different failing checkpoint — not a fresh alarm each day for the same break. A subsequent clean run clears the alert on its own; a later, different break raises a new one. ## Tampering or a configuration gap The alert arrives in two shapes, and the title tells you which. **Audit log integrity check failed** is the critical one: the hash chain itself does not verify, or a signed checkpoint's signature does not match the configured key. Treat this as a possible tamper signal until you have explained it. **Audit log signatures can't be verified** is a calm warning, not a breach: a checkpoint is signed, but the deployment has no `TALE_AUDIT_SIGNING_KEY` configured to check that signature against. Nothing was forged — Tale cannot prove the checkpoint is authentic until you restore the key. The in-product panel mirrors the split: a healthy chain shows a green **Verified** badge, an active incident shows a red **Integrity alert active** badge, and an organisation the cron has not reached yet shows **Not yet checked**. ## Open the integrity panel An organisation's admins inspect the chain from **Settings > Governance > Logs**. The **Chain integrity** panel at the top of the page shows the status badge, the time of the last automated check, and a **Verify now** button that re-runs the same verification on demand. If you arrived from the notification, clicking the alert deep-links you straight to the flagged row in the audit table instead of the top of the log. Run **Verify now** to see the structured finding. For a hash-chain break, the panel shows **Chain integrity broken** with the **Entry ID** of the first row that fails, when it **Occurred**, the **Expected hash**, and the **Stored hash** that did not match — plus an **Open this entry** button that reveals the row in the table. For a checkpoint problem, it shows **Checkpoint verification failed** with the **Checkpoint ID** and a **Reason**. Record these details before you change anything: they are the evidence. ## Rule out the benign causes A hash break is a tamper signal only when nothing legitimate explains it, and the verifier already accounts for the three ordinary events that cause almost every alert — so confirming one of them is your first move. **A retention cut.** When retention hard-deletes old rows, the surviving chain head points at a row that no longer exists. The verifier re-anchors across the cut using a signed retention checkpoint, so a clean cut verifies normally. If instead you see **Audit log signatures can't be verified**, the cut itself is fine — the deployment is missing the `TALE_AUDIT_SIGNING_KEY` that authenticates the checkpoint. That is a configuration gap, not tampering. **A GDPR scrub.** Erasing a data subject blanks their fields in place, which would change those rows' hashes — so a scrub writes a signed scrub checkpoint covering the affected rows, and the verifier trusts them on that basis. A scrub should never surface as a break on a deployment that has a signing key. **Legacy pre-chain rows.** Rows written before audit hash-chaining existed carry no integrity hash. The verifier skips them automatically; they are not a break. A genuine tamper signal is a hash mismatch with none of these explanations: no retention cut at that point, no scrub covering the row, and the signing key present and correct. ## Respond to a real break If the finding survives that triage — a hash mismatch you cannot account for — treat it as a security incident and preserve evidence first. Audit rows are append-only by design; do not delete or edit any row, including the flagged one, because that destroys the record an investigation depends on. 1. Record the finding verbatim — the **Entry ID**, **Occurred** time, **Expected hash**, and **Stored hash** (or the **Checkpoint ID** and **Reason**) shown in the panel. Copy or screenshot them rather than relying on the alert alone. 2. Confirm whether the signing key is configured on the host, so you can tell a real mismatch from an unverifiable checkpoint. This reports presence without printing the secret: ```bash grep -q '^TALE_AUDIT_SIGNING_KEY=' .env && echo configured || echo missing ``` 3. Correlate the break's timestamp with recent activity — a retention sweep, a data-subject scrub, a deploy, a database restore, or direct database access. A break that lines up with a maintenance action usually has an ordinary cause you can now name. 4. If nothing explains it, escalate through your security incident policy and treat the database as potentially compromised until proven otherwise. Keep a backup snapshot from before and after the detected break for forensics. ## Clear the alert The alert is incident-based, not a recurring event. Once the break is resolved or explained — the key restored, the retention artifact understood, a tampered database rebuilt from a clean backup — the next daily run verifies cleanly and clears the alert on its own, and the **Chain integrity** badge returns to **Verified**. There is no acknowledge or dismiss step to remember. If a different break appears later, the check raises a fresh alert for that one, so muting is never necessary. ## Where this fits An integrity alert is a prompt to investigate, not a verdict — the daily check runs loud so a rare real break cannot hide among the logs, and this runbook is how you separate that rare case from the retention and scrub artifacts behind most alerts. The mechanism the verifier checks — the SHA-256 hash chain and the HMAC-signed checkpoints — is documented in [Cryptography](/self-hosted/operate/security/cryptography), and the retention cuts that legitimately re-anchor it are in [Retention](/self-hosted/configuration/retention). The panel, columns, and export you use to read a flagged row live on the [Audit logs](/platform/admin/governance/audit-logs) reference; the [Hardening](/self-hosted/operate/security/hardening) checklist is where this monitoring gets switched on in the first place. # Cryptography Source: https://tale.dev/docs/self-hosted/operate/security/cryptography This page is the inventory of every cryptographic primitive Tale relies on: what protects secrets on disk, what protects traffic on the wire, how passwords are hashed, and how the audit log proves it has not been tampered with. It is written for operators and compliance reviewers who need to answer "which algorithms, which key lengths, where are the keys" against a standard such as BSI TR-02102-1 — Tale already uses compliant primitives, and this page is where they are written down. The claims here are verified against the source; where a primitive is configurable, the environment variable that controls it is named so you can audit your own deployment. None of this is a substitute for encrypting the host disk — see [Hardening](/self-hosted/operate/security/hardening) for the layer below the application. ## Data at rest Tale encrypts two classes of secret at rest, with two different mechanisms. **Provider API keys** live in `providers/*.secrets.json` and are encrypted with [SOPS](/self-hosted/configuration/secrets-with-sops) using an **age** key. SOPS encrypts each value with **AES-256-GCM** and wraps the data key to the age recipient, whose key agreement is **X25519**. An encrypted value reads `ENC[AES256_GCM,data:…,iv:…,tag:…]` on disk; decryption happens in-process and the age private key never leaves the platform container's memory. **Application-encrypted fields** — OAuth integration tokens and similar credentials stored in the database — are encrypted with **AES-256-GCM** through a compact JWE (`alg: dir`, `enc: A256GCM`). The 32-byte key comes from `ENCRYPTION_SECRET` (base64) or `ENCRYPTION_SECRET_HEX` (hex); the platform refuses to start the encryption path with a key that is not exactly 32 bytes. The Convex data store and Postgres volumes are protected by the host: run them on an encrypted filesystem (LUKS, or your cloud provider's volume encryption). Tale does not store credentials in plaintext — a provider key or OAuth token is either SOPS-encrypted on disk or AES-256-GCM-encrypted in the database, never written in the clear. **Customer PII and application records** — names, email and postal addresses, conversation content — are protected at rest by the same layers that protect the database as a whole: Convex's at-rest encryption, TLS 1.3 in transit, and row-level security that scopes every read to the caller's organisation. Application-level field encryption is purpose-built for secrets — provider keys and OAuth tokens, written once and read by a single code path. PII is different: it is filtered, sorted, and looked up by exact value, and the customer table is indexed by organisation and email. Encrypting those columns at the field level would break equality lookups and indexed search — unless paired with a searchable-hash scheme that leaks the very equality it is meant to hide — while adding a key-rotation cost and no protection the encrypted host disk beneath the application doesn't already provide against a stolen volume. If your compliance regime calls for field-level PII encryption on top of these layers, that is a deliberate application change rather than a default Tale ships. ## Data in transit All browser and API traffic terminates TLS at the reverse proxy (Caddy), which negotiates TLS 1.3 (with TLS 1.2 as the floor) and obtains certificates automatically. The cipher suites are the proxy's modern defaults — AES-256-GCM and ChaCha20-Poly1305 with ECDHE key exchange. Configure the domain and certificate source in [TLS and domains](/self-hosted/configuration/tls-and-domains); traffic between containers stays on the host's internal Docker network. ## Password hashing Local-password accounts are hashed with **bcrypt** (via Better Auth), so a stolen database row does not reveal the password and a verification deliberately costs ~100 ms — which is also why the login path's timing is fuzzed (see [Authentication](/self-hosted/configuration/authentication)). Sessions are signed with `BETTER_AUTH_SECRET` (HMAC); rotating that secret invalidates every existing session. ## Audit-log integrity The audit log is tamper-evident through a **SHA-256 hash chain**: each entry stores `SHA-256(previousHash + canonicalized record)`, so altering or deleting any historical entry breaks the chain at that point and every entry after it. Entries additionally carry an **HMAC-SHA-256** signature. The admin integrity-check verifies both; see [Audit logs](/platform/admin/governance/audit-logs). ## Mapping to BSI TR-02102-1 Every primitive below is in the recommended set of BSI TR-02102-1. Tale does not ship any deprecated algorithm (no MD5, SHA-1, DES, or RSA < 3072 on a key it generates). | Use | Algorithm | Key / output size | Controlled by | | ----------------------- | --------------------------------- | ----------------- | --------------------------------------------- | | Provider secrets (disk) | AES-256-GCM + age (X25519) | 256-bit | `SOPS_AGE_KEY` / `SOPS_AGE_KEY_FILE` | | App fields (database) | AES-256-GCM (JWE `dir`/`A256GCM`) | 256-bit | `ENCRYPTION_SECRET` / `ENCRYPTION_SECRET_HEX` | | Transport | TLS 1.3 (AES-256-GCM, ECDHE) | 256-bit | Reverse proxy / `tls-and-domains` | | Password hashing | bcrypt | per-hash salt | Better Auth (built in) | | Session signing | HMAC-SHA-256 | 256-bit | `BETTER_AUTH_SECRET` | | Audit integrity | SHA-256 chain + HMAC-SHA-256 | 256-bit | built in | ## Key storage and rotation Three secrets are load-bearing, and each has a rotation path. The **age private key** (`SOPS_AGE_KEY`) decrypts provider secrets; rotate it by adding a new recipient and re-encrypting, following the walk in [Secrets with SOPS](/self-hosted/configuration/secrets-with-sops). The **field-encryption key** (`ENCRYPTION_SECRET`) decrypts database credentials; rotating it requires re-encrypting the affected rows, so plan it as a maintenance step rather than a hot swap. The **auth secret** (`BETTER_AUTH_SECRET`) signs sessions; rotating it logs everyone out on their next request. All three live only in the platform container's environment — never commit them, and store them in your secret manager of record. ## Where this fits Cryptography in Tale is layered: SOPS+age and AES-256-GCM protect secrets at rest, TLS 1.3 protects them in transit, bcrypt protects passwords, and a SHA-256 chain proves the audit log is intact — all primitives that sit inside BSI TR-02102-1's recommended set, with the controlling environment variables named above so you can verify your own instance. The layer beneath the application is the host itself: [Hardening](/self-hosted/operate/security/hardening) covers the egress allowlist, container isolation, and disk-encryption expectations that this page assumes, and [Secrets with SOPS](/self-hosted/configuration/secrets-with-sops) is the operational walk-through for the age key these algorithms depend on. # Hardening Source: https://tale.dev/docs/self-hosted/operate/security/hardening The defaults Tale ships with are safe for development and reasonable for a small production install. Going from "reasonable" to "ready for the regulator" is a checklist, not a configuration flag — every row below tightens one specific attack surface. Walk the list once before opening the URL to real users, and run it again after every major upgrade. The reference detail for each row lives elsewhere — TLS in [TLS and domains](/self-hosted/configuration/tls-and-domains), backups in [Backups and restore](/self-hosted/operate/backups-and-restore), retention in [Retention](/self-hosted/configuration/retention). This page is the index that names what to harden and points at the page that walks it. ## Host | Item | Why it matters | | ------------------------------ | ------------------------------------------------------- | | Non-root operator user | Limits blast radius if the platform user is compromised | | SSH key auth only | Password auth is the open door bots scan for | | Unattended security updates | Patches the OS without waiting for a maintenance window | | Host firewall (ufw / nftables) | Closes everything that is not 22, 80, 443 | | Disk encryption at rest | Required if you run SOPS in plaintext mode | The non-root user is the one most teams skip. Tale's containers run their own non-root processes inside, but the docker daemon itself runs as root — operating that daemon as the operator user (member of the `docker` group, not as root) is the cheapest tightening on this page. The full walk lives in [Production Linux server install](/self-hosted/install/linux-server). ## Network The proxy is the only inbound surface. Block everything else. ```bash sudo ufw default deny incoming sudo ufw default allow outgoing sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable ``` If you run trusted-headers auth, the platform port must not be reachable directly from anywhere except the upstream proxy — anything that can hit it with the right headers becomes that user. A Docker network or a host firewall rule both work; pick one and verify it from outside the host. ## TLS `TLS_MODE=selfsigned` is for development. Production runs `letsencrypt` (or `external` if you front Tale with your own TLS-terminating proxy). The renewal cron is automatic; the alert that fires when renewal fails is what saves you 90 days later. See [TLS and domains](/self-hosted/configuration/tls-and-domains). ## Secrets Every secret in `.env` is sensitive — the auth signing secret, the encryption key, the database password, the age key, the metrics bearer token. The minimum bar: - `.env` is mode 0600 and owned by the operator user. - `BETTER_AUTH_SECRET`, `ENCRYPTION_SECRET_HEX`, `INSTANCE_SECRET` are rotated off the example values that ship in `.env.example`. - `DB_PASSWORD` is changed from the default placeholder. - `SOPS_AGE_KEY` or `SOPS_AGE_KEY_FILE` is set — leaving both unset is supported but reserved for disk-encrypted hosts with external secret management. The full SOPS walk and rotation procedure lives in [Secrets with SOPS](/self-hosted/configuration/secrets-with-sops). ## Audit logs Audit logs are immutable and retention-bound. Compliance frameworks expect at least a year; the bound is enforced per-deployment, so the strictest org's setting is what actually runs. Set the floor in your operator config to match the loosest framework you support, and make sure backups capture audit-log rows along with the rest of the database. The retention reference lives in [Retention](/self-hosted/configuration/retention). ## Backups A backup that has not been restored is a hope, not a backup. The minimum: daily Postgres dumps written by the `tale-db` cron, copied off-host within the hour, and a quarterly restore drill that rebuilds a working instance from the snapshot. The full procedure is in [Backups and restore](/self-hosted/operate/backups-and-restore). ## Sandbox isolation Run-code is the riskiest surface in the product — the only place where user-supplied input becomes executed code. `tale-sandbox` runs with no privileged caps, its network is internal-only, and `tale-sandbox-egress` is its only outbound path. At the hostname layer that path is open by default: sandboxed code reaches any public host over HTTPS, while cloud-metadata endpoints and private address ranges are always blocked at the IP layer — that floor holds in every configuration. The hardening lever is `SANDBOX_EGRESS_ALLOWLIST`. Set it in `.env` to a pipe-separated list of hostname regexes and recreate `tale-sandbox-egress`, and the proxy flips to default-deny — only matching hosts are reachable. A registry-only lockdown that keeps pip, npm, uv, and git-over-HTTPS working: ```bash SANDBOX_EGRESS_ALLOWLIST=^pypi\.org$|^files\.pythonhosted\.org$|^registry\.npmjs\.org$|^objects\.githubusercontent\.com$|^codeload\.github\.com$|^github\.com$|^api\.github\.com$ ``` Keep the list short and prefer specific hosts over wildcards. Package installs are gated separately, through the [run-code policy](/platform/admin/governance/run-code-policy) screen. ## Monitoring `METRICS_BEARER_TOKEN` is unset in `.env.example` — that is intentional, so a fresh install does not leak metrics. Set the token, scrape from your Prometheus, and the alert thresholds in [Operations](/self-hosted/operate/observability/operations) cover the customer-impacting signals. The audit-log hash chain is verified automatically every night by a scheduled integrity check. A genuine break raises a critical security alert to the organisation's admins — in the notification bell, and in your Slack channel when one is connected — so tampering surfaces even when nobody is watching the logs; a signed checkpoint that can't be verified because `TALE_AUDIT_SIGNING_KEY` is unset alerts more calmly, as the configuration gap it is. The alert fires once when a break is first detected or when it changes, not every day for the same break. Admins re-run the verification on demand from the **Chain integrity** panel on **Settings > Governance > Logs** — a status badge, the last-check time, and a **Verify now** button. When one fires, work the [audit-log integrity runbook](/self-hosted/operate/security/audit-log-integrity) to tell a real break from a benign retention or configuration artifact. ## Where this fits Hardening is not a one-pass task — the list above is what to walk before launch, and re-walk after every upgrade or after every change to the network shape. The next thing worth reading after this is whichever row above you have not done yet. # tale-daemon Source: https://tale.dev/docs/self-hosted/operate/tale-daemon `tale-daemon` executes Tale board tasks on a machine you control, using the coding-agent CLIs you already have: **Claude Code** (`claude`) and **Codex** (`codex`). Bind an agent to a runtime in its configuration and its assigned tasks are dispatched to the daemon instead of Tale's internal model loop; the result lands back on the task as a comment (with a diff stat) and the task parks at _In review_ like any other agent work. For chat-driven runs of the same CLIs inside a managed sandbox, see [External agents](/platform/agents/external-agent). ## Setup ```sh tale daemon setup # base URL, API key, workspace, permission ceiling tale daemon start # register + claim loop (Ctrl-C drains the run) tale daemon status # config, detected CLIs, server connectivity ``` `setup` generates a stable daemon identity and stores configuration at `~/.tale-daemon/config.json` (mode 600). Use a normal Tale API key (**Settings → API → REST**); set `TALE_DAEMON_API_KEY` to keep the key out of the file. Connected daemons appear under **Settings → API → Runtimes** with live status. The fastest path is the **Generate key & copy command** button under **Settings → API → Runtimes**: it mints a fresh API key and copies a ready-to-run command with this workspace's URL and the key already filled in. Any answer `setup` prompts for can also be passed as a flag, so the command runs unattended: ```sh tale daemon setup --yes --url https://your-org.tale.dev --key <api-key> tale daemon start ``` The key is embedded in the command line, so treat the snippet as a secret and revoke the key under **Settings → API → REST** if it leaks. ## Privacy & permissions - Local workspace **paths never leave the machine** — only the workspace _keys_ you choose are advertised to the server. - The effective permission of a run is **min(server-configured, daemon ceiling)**. `full_auto` (skip-permissions / full sandbox access) therefore requires opting in on _both_ sides. The default is `safe`. ## How runs execute - **Pacing**: the daemon polls for work with server-driven backoff (3 s after work, 15 s idle, capped at 60 s after ten idle minutes — an idle daemon costs about one request per minute). A 15 s heartbeat during runs renews the server lease and picks up cancellations (SIGTERM). - **Isolation**: every run executes in its own git worktree on a `tale/run-…` branch. Nothing is pushed; the diff stat rides along with the report. - **Sessions**: revision runs (review feedback) resume the previous CLI session where the adapter supports it. ## Failure handling | Situation | Behavior | | --------------------------------------- | ------------------------------------------------------------------------ | | No daemon claims a run within 2 minutes | Run fails (`runtime_offline`), task rolls back to _To do_ with a comment | | Daemon dies mid-run (lease lost) | One retry from a clean worktree, then failure | | Run exceeds 30 minutes | Hard timeout, failure handling as above | | CLI exits non-zero | One retry, then failure with the error excerpt | All external runs share the internal run record, so budgets, concurrency caps, and metrics apply identically. # Upgrades Source: https://tale.dev/docs/self-hosted/operate/upgrades Upgrades on a self-hosted Tale instance run through two commands: `tale update` moves the CLI binary to the new version and syncs your project files to match, then `tale deploy` rolls the platform containers. The deploy uses a blue-green pattern — the new colour starts alongside the old, healthchecks pass, traffic flips, the old colour drains. Zero downtime is the default; if a patch release misbehaves, `tale rollback` returns to the previous patch in one command, and anything bigger recovers from the pre-upgrade snapshot. What you no longer do is keep the CLI in sync by hand: the CLI aligns itself to the instance automatically (see below), so the only deliberate step is choosing when to move versions with `tale update`. The CLI install lives in [Install the tale CLI](/self-hosted/install/cli-install). This page covers what each command does and how the version model works. ## The CLI tracks the instance automatically The CLI binary is always the same version as the instance it manages. The workspace records that version in `tale.json`; on every command the CLI compares its own version against it and, if they differ, self-updates the binary to match (up or down) before running. When they already match — the overwhelmingly common case — this is a no-op with no network call, so you never notice it. That means you rarely run `tale update` except when you deliberately want to move to a new version. A teammate who installed a newer CLI than your instance, or restored an older snapshot, gets the right CLI version automatically on their next command. There is no flag to turn this off — keeping the tool and the instance in lockstep is what makes deploys safe. ## Before you upgrade Two things are worth confirming first: - Your off-host copy of the `backups` volume is current — see [Backups and restore](/self-hosted/operate/backups-and-restore). `tale update` snapshots the data volumes automatically before any step that can migrate data, but the snapshot lives on the same host; the off-host copy is what survives a dead disk. - The release notes for the target version do not name a breaking change. The notes are linked from the GitHub release page; breaking changes are flagged as such at the top. If the upgrade crosses a major version (1.x → 2.x), read the migration notes end-to-end before starting. Major versions are where schema migrations and config-file format changes land. ## The two commands `tale update` updates the CLI binary and then syncs your project files to that version's templates. It does **not** touch the running containers — that is `tale deploy`'s job. If the file sync fails, the CLI rolls its own binary back to the version your workspace was on, so the binary and `tale.json` never drift apart. ```bash # Move the CLI + project files to the latest release tale update # Pin a specific version (allows downgrades — see Rolling back) tale update --version 0.10.2 # Preview the version change and file sync without touching anything tale update --dry-run ``` `tale deploy` does the actual rolling restart, and it always deploys the CLI's own version — which, thanks to alignment, is the version your workspace records. It sorts the services into three tiers: - **App tier** — `platform` — rolls on **every** deploy with zero downtime (blue-green: the new colour starts alongside the old, healthchecks pass, traffic flips, the old colour drains). - **Backend & compute** — `convex`, `sandbox`, `sandbox-egress` — roll on every deploy too, so they never version-skew from `platform`. Each is a single container that recreates **in place** when its image actually changed; the deploy first drains its in-flight work (chat generations for `convex`, agent runs for `sandbox`) so the brief restart doesn't cut a live request. - **Stop-gated tier** — `db`, `proxy` — left **running and untouched** by default (recreating Postgres or the proxy is a brief outage you don't want on a routine roll). Pass `--stop` to update them; the deploy warns and names them when it skips. ```bash # After tale update, roll the containers to match (app tier + convex) tale deploy # Also update db/proxy (brief downtime while they recreate) tale deploy --stop # Roll only specific services tale deploy --services platform # Preview without changes tale deploy --dry-run ``` `--dry-run` is worth running before every production upgrade — it surfaces missing images, missing migrations, and dependency mismatches without touching the running containers. ## The blue-green pattern A running instance is one of the two colours (blue or green) at any given time. The deploy phase brings up the other colour, waits for it to pass healthchecks, then flips Caddy's upstream to the new colour. The old colour drains its in-flight requests (default 30 s), then exits. Three guarantees the pattern gives you: - **No window where both colours serve traffic.** A database constraint enforces single-active — Caddy routes to the healthy one. - **Patch rollback is one command.** `tale rollback` redeploys the previous patch release on the idle colour and flips traffic back. It refuses minor and major downgrades — those can leave the database ahead of the binary, and their recovery path is a snapshot restore. - **Failed healthchecks block the flip.** If the new colour does not pass within the timeout, the deploy aborts and the old colour continues serving. The full deploy procedure including the cleanup phase lives in `tale --help`; the operator-facing recipe is `tale update && tale deploy && tale status` and visual confirmation in the browser. ## Working with data migrations Every deploy applies pending data migrations automatically — but only the non-destructive ones. Migrations that remove or overwrite data (a table drop, a column removal) are never run unattended: the deploy skips them, prints which ones are waiting, and leaves the decision to you. ```bash # What is applied, what is pending, what failed tale migrate status # Apply pending migrations, reviewing each destructive step tale migrate up --step # Apply everything without prompting (CI / after reviewing the plan) tale migrate up --yes # Roll data back to an earlier version tale migrate down --to 0.3.3 ``` Destructive migrations snapshot the affected rows or config files before touching them, so `tale migrate down` can rebuild what they removed. Both directions are resumable: progress is tracked per migration (and per organization for config-file migrations), so a crash or timeout picks up where it stopped instead of starting over. If a migration fails during a deploy, the platform still boots on its current schema — the boot log prints a prominent error and `tale migrate status` shows the failed migration with the recorded error. Fix the cause, then re-run `tale migrate up`; already-completed work is skipped. ## Rolling back ```bash # Back to the previous patch version (prompts for confirmation) tale rollback # Skip the prompt when running non-interactively tale rollback --yes ``` `tale rollback` is gated to patch-level steps: it only targets the recorded previous version, and refuses unless that version shares `major.minor` with the running platform. Patch releases never carry migrations, so redeploying the previous patch is always safe. Anything bigger may have migrated data forward — redeploying an older binary on top of migrated data corrupts the instance instead of recovering it. For those, the recovery path is restoring the pre-upgrade snapshot and moving back to the version that matches it with `tale update --version <version>` followed by `tale deploy --stop` (so `db`/`proxy` roll back too); the refusal message prints the exact commands, and the full walk lives in [Backups and restore](/self-hosted/operate/backups-and-restore). Because the rollback tears down the running containers, the command warns what it is about to do and asks for confirmation before it pulls a single image; pass `--yes` to skip that prompt in scripts or CI. ## Version compatibility Tale versions are semver. The compatibility rules: - Patch (`0.9.0 → 0.9.1`) — no migrations, no config changes, `tale rollback` is always safe. - Minor (`0.9.x → 0.10.x`) — may include forward-only migrations; `tale rollback` refuses, recovery is restore-snapshot-and-redeploy. - Major (`0.x → 1.x`) — read the migration notes, schedule the maintenance window, expect surprises. Skipping minor versions (going from 0.9 to 0.11) is supported as long as the intermediate migrations are still in the binary; the release notes call it out when this is not the case. To move _down_ a version deliberately — say a minor release misbehaves and you have already reversed its migrations — pin the target with `tale update --version <version>`. The command warns when the target is older than the running version and reminds you to reverse data migrations first. ## Upgrading from 0.3.1 or earlier Instances on version 0.3.1 or earlier keep the Convex backend's data in the `platform-data` Docker volume. Newer versions run Convex as its own service with its own `convex-data` volume — and nothing moves the data across at deploy time. Upgrade straight across that boundary and `tale deploy` pre-creates an **empty** `convex-data` volume: the instance comes up blank while every byte of your data still sits, untouched, in the old `platform-data` volume. Nothing is deleted — but the data does not move by itself, and `tale update` warns when it detects this constellation and offers to run the copy for you on the spot. Docker has no native volume rename, so the move is a copy through a helper container — the same steps `tale update` runs when you accept its prompt (the old volume stays preserved either way). To do it by hand — you declined the prompt, or the automatic copy failed — run it before `tale deploy`, with the stack stopped, so nothing holds the volume open: ```bash # 1. Find the legacy volume — <project> is the `id` in tale.json. docker volume ls | grep platform-data # Installs older than 0.2.33 used the fixed prefix `tale_` instead # of `<project>_`; the destination below still uses `<project>_`. # 2. Stop the running stack. docker compose -p <project> down # 3. Create the destination volume and copy the data across. docker volume create <project>_convex-data docker run --rm \ -v <project>_platform-data:/from:ro \ -v <project>_convex-data:/to \ alpine sh -c "cd /from && cp -a . /to" # 4. Roll the stack, then verify your data is there. tale deploy # 5. Only after verifying, reclaim the old volume. docker volume rm <project>_platform-data ``` A dev workspace mirrors the same move under the `-dev` scope: `<project>-dev_platform-data` → `<project>-dev_convex-data`, with `docker compose -p <project>-dev down` as the stop step. If you already deployed and got an empty instance, your data is still safe in `platform-data`. Stop the stack, remove the freshly created empty volume with `docker volume rm <project>_convex-data`, then run the copy above and deploy again. ## Where this fits The upgrade flow ties together every other operate page — backups are what makes a failed upgrade recoverable, observability is what tells you the new colour is healthy, hardening is what you re-walk after a major version. If you are setting up the CLI for the first time, [Install the tale CLI](/self-hosted/install/cli-install) covers the workstation-side setup; if you are picking up the pager mid-rollout, [Troubleshooting](/self-hosted/operate/observability/troubleshooting) names the symptoms. # Self-hosted architecture Source: https://tale.dev/docs/self-hosted/overview A Tale instance is eight containers behind a Caddy proxy, talking to two Postgres databases — one operational, one for the knowledge corpus; two of them are sandbox containers off to the side for code execution. The compose file is the contract — what runs, what is exposed, what is mounted. This page hands you the mental model so the install, configure, and operate pages do not have to re-explain it. Read this before you `docker compose up`. Come back when you are debugging an outage and need to know which container's logs to open first. ## The eight containers **tale-proxy** is Caddy at the edge. It terminates TLS, routes everything under `/` to the platform container, and forwards everything under `/api/` and the Convex paths to the convex container. Healthchecks live here. **tale-platform** is the React + TanStack Start server. It renders the UI, serves static assets, and is the only container exposed to the browser. It does not hold business state — everything that needs to persist talks to convex. **tale-convex** is the backend: the actions, queries, mutations, and the WebSocket layer the UI subscribes to. Provider keys, agent definitions, workflow runs, audit logs all live here. It also runs the knowledge work in-process — document ingestion, web crawling, RAG search, and document generation are Convex node-actions, not separate services. The headless work those jobs need (rendering a web page, turning HTML into a PDF or image) is delegated to the sandbox runtime, which already ships Chromium and Playwright. **tale-db** is the operational Postgres (ParadeDB). It holds the Convex backend data — agents, runs, the audit log — and is one of the two stateful containers that matter for backups. **tale-knowledge-db** is the knowledge corpus Postgres (ParadeDB), the `tale_knowledge` database with two schemas: `private_knowledge` (uploaded-document chunks, embeddings, the BM25 index, the semantic cache) and `public_web` (crawled web pages). It is split from `tale-db` so the corpus — the data-residency-sensitive store — can be relocated or replaced on its own. The Convex backend connects to it directly; nothing else does. **tale-sandbox-llm-gateway** is the LLM gateway for in-sandbox coding agents. It is the only path from a sandboxed agent to a model provider; the platform provisions it and mints per-session keys. **tale-sandbox** and **tale-sandbox-egress** run sandboxed code on behalf of the `Run code` tool and skill scripts, and serve as the headless-browser runtime the convex backend calls for web rendering and document generation. The egress container is the only path the sandbox has to the network. Egress is open by default — sandboxed code reaches any public host over HTTPS while cloud-metadata and private-range targets stay blocked at the IP layer; lock it down to a hostname allowlist with `SANDBOX_EGRESS_ALLOWLIST`, described in [Hardening](/self-hosted/operate/security/hardening). One more service ships but stays off by default: **tale-controller** is an opt-in sidecar (the `controller` compose profile) that restarts the convex container on a signed request from the app, so a data-residency change can apply without giving the browser-facing platform Docker-socket access. ## Data on disk Four volumes survive a `docker compose down`: - `db-data` — the operational Postgres data directory: the database behind agents, runs, and the audit log. - `knowledge-db-data` — the knowledge corpus Postgres data directory: document chunks, embeddings, the search indexes, and crawled web pages. Backs up separately from `db-data` because it is a separate database. - `backups` — checksummed volume snapshots written by `tale backup` and automatically before migrating deploys; [Backups and restore](/self-hosted/operate/backups-and-restore) is the drill. - The convex object-store mount — uploaded files, generated documents, exported bundles. Everything else is ephemeral. Containers can be replaced without data loss as long as the volumes survive. ## Provider secrets and the SOPS layer Provider keys (OpenAI, Anthropic, Azure, Ollama, etc.) live on disk in a `providers/` directory mounted into the platform container. Each provider has a `<name>.json` and a `<name>.secrets.json`; the secrets file is encrypted with SOPS and the [`SOPS_AGE_KEY`](/self-hosted/configuration/environment-reference) variable. This split exists for two reasons. Rotating a provider key is editing one file, not re-running the platform; backing up the encrypted file is safe to commit alongside infrastructure. The plaintext mode (no SOPS, secrets in cleartext) is supported for tightly controlled environments where the disk itself is encrypted at rest. ## Auth and sessions Sign-in is Better Auth running inside the convex container. Four sign-in modes ship: local password, Microsoft Entra (OAuth/OIDC), generic OIDC, and trusted headers (the reverse proxy provides the identity). The platform container reads the cookie, hands it to convex, and convex decides what the session can do based on the user's role and the per-resource permission matrix documented in [Members and roles](/platform/admin/members-and-roles). The [authentication reference](/self-hosted/configuration/authentication) covers the env vars and the per-mode trade-offs. ## When you outgrow single-host The default compose file runs all eight containers on one host. The architecture is single-tenant: nothing in the design splits work across hosts. The first thing you can move off the box without re-architecting is the knowledge corpus — `tale-knowledge-db` is a standalone Postgres, so pointing it at managed infrastructure (for capacity or for a residency requirement) is a connection-string change, covered in [Data residency](/self-hosted/configuration/data-residency). The Convex layer is still single-instance; horizontal scaling of the backend is not a v1 feature. ## Where this fits This architecture page is the map every other self-hosted page assumes. The natural next read is [Quickstart](/self-hosted/install/quickstart) if you are setting up a fresh instance, or [Container architecture](/self-hosted/operate/container-architecture) if you are operating one and need the same picture with the failure modes overlaid. # Connect a local LLM provider Source: https://tale.dev/docs/tutorials/admin/connect-local-provider A local provider is the path to running models inside your own perimeter — no outbound API calls, no per-token bill, no third-party transcript. This walk takes a self-hosted Tale instance from "I have an Ollama, LM Studio, or vLLM endpoint" to "an agent in the org calls a local model and the reply streams back." The walk is for an Admin on a self-hosted install; Cloud orgs do not reach onto your network and skip this page. You need the Admin role in Tale, a local inference server reachable from the `tale-platform` container, and a model already pulled or loaded on that server. The underlying provider mechanic is documented in [Providers](/self-hosted/configuration/providers); this page walks the UI path and verifies the result end to end. ## Before you begin Confirm four things. Your role is Admin or Owner — the **Providers** panel is hidden below that. Your local inference server is running and answers `GET /v1/models` (or the Ollama equivalent `GET /api/tags`) from inside the Tale Docker network. At least one model is loaded — Ollama users have run `ollama pull llama3.1:8b` or similar, LM Studio users have a model loaded in the server tab, vLLM users have started the server with `--model` pointed at a checkpoint. And the network path from `tale-platform` to the inference host is open on the inference port (typically `11434` for Ollama, `1234` for LM Studio, `8000` for vLLM). ## Step 1 — Make the inference server reachable from Tale The first move is confirming that `tale-platform` can reach the inference server by hostname. Without that, every model call surfaces a connection error and the picker shows the provider as **error**. When the inference server runs on the same Docker host, the reachable hostname depends on where the server itself runs. An Ollama container in the same compose network is `http://ollama:11434`. An LM Studio or vLLM server running on the host (outside compose) is `http://host.docker.internal:1234` on macOS and Windows, or the host's bridge IP on Linux. Run a one-shot curl from the `tale-platform` container to verify before opening the UI: ```bash docker compose exec platform curl -sf http://ollama:11434/api/tags ``` A JSON list of pulled models is the success signal. A connection-refused error means the hostname is wrong or the inference server is not listening on the interface the container can reach. ## Step 2 — Register the provider in Tale A reachable server does nothing until Tale knows the URL and the protocol shape it speaks. The provider entry tells Tale where to send requests and which OpenAI-compatible dialect to use. Open **Settings > Providers** and click **Add provider**. Pick the provider type that matches your server: **Ollama** for an Ollama server, or **OpenAI-compatible** for LM Studio and vLLM (both expose the OpenAI `/v1` shape). Fill the **Base URL** with the value you verified in Step 1; leave the API key field empty for Ollama, set it to any string for LM Studio (the server ignores it), set it to your configured token for vLLM if you started the server with `--api-key`. Click **Save**. Tale immediately calls the provider's model-list endpoint; the row turns green and the model picker fills with whatever the server reported. ## Step 3 — Allowlist the models you want callable A registered provider with no allowlisted models is invisible to every agent. The allowlist is the contract between the org and the provider — picking the model is the gate. In the provider row, expand the model picker. Each model from the upstream list shows a checkbox plus the tag Tale inferred (`chat`, `embedding`, `vision`). Tick the models you want agents to call; a chat-tagged model is what an agent binds to by default. Click **Save allowlist**. If you want the local model to be the org-wide default for new chats, scroll to the top of the provider list and pick it under **Default model**. Existing agents keep their previous binding; new ones land on the local model on the next request. ## Step 4 — Verify with an agent chat The proof the wiring works is one chat reply streaming from the local server. Without this step you do not know whether the model picker just _looks_ right. Open or create an agent, set its model to one of the local models you allowlisted, and start a chat with a short prompt (`Reply with the single word "ready"`). The reply streams in tokens within a few seconds; the chat's tool-call card shows the model name and the provider you registered. Tail the inference server log on the host while you send the prompt — Ollama logs the request line, LM Studio prints a request summary, vLLM prints the generation latency. Seeing the request hit the local server is the verification that traffic is staying inside your network, not bouncing through an external API. ## Troubleshooting - **Symptom:** provider row shows **error** with `connection refused`. **Cause:** the base URL is unreachable from the `tale-platform` container. **Fix:** repeat the `docker compose exec platform curl` from Step 1; adjust the hostname (often `host.docker.internal` on macOS/Windows, the bridge IP on Linux). - **Symptom:** the model picker is empty after **Save**. **Cause:** the inference server is reachable but has no models loaded. **Fix:** run `ollama pull <model>` or load a model in LM Studio / vLLM, then click **Refresh models** on the provider row. - **Symptom:** the chat reply is one error toast (`model not found`). **Cause:** the model name the agent is bound to does not match the upstream id. **Fix:** open the agent's model dropdown and re-pick from the live list — Ollama tags like `:latest` matter to the upstream and must match exactly. - **Symptom:** saving the provider is rejected because the base URL points at `localhost`, `127.0.0.1`, or a private IP. **Cause:** Tale blocks private and loopback provider hosts by default as an SSRF safeguard. **Fix:** use the in-network hostname instead (`http://ollama:11434`, `http://host.docker.internal:1234`); if you must point at a private or loopback address, set `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS=1` on the platform service. ## Where this fits A local provider is the seam between Tale and your own GPUs — same allowlist mechanics as a cloud provider, but no traffic leaves the host. The natural next reads are [Providers](/self-hosted/configuration/providers) for the file-form equivalent of what you just did in the UI, and [Hardening](/self-hosted/operate/security/hardening) for the egress-allowlist guarantees that keep an agent from accidentally falling back to a cloud model when the local one is unreachable. # Pipe meeting transcripts into the Knowledge Base Source: https://tale.dev/docs/tutorials/admin/meeting-transcription A meeting transcript is one of the highest-value documents a project can keep — names, decisions, follow-ups, all in one searchable place. This walk integrates Meetily, a local meeting-transcription tool, with a Tale project so every transcript Meetily produces lands in the project's Knowledge Base as a document on its own. The walk is for an Admin on a self-hosted Tale instance pairing it with a Meetily install on the same network. You need an Admin role in Tale, a Meetily install reachable from the `tale-platform` container, and one project in Tale with a Knowledge Base you want the transcripts routed into. The Knowledge Base concept lives in [Knowledge Base](/platform/knowledge/overview); this page is the integration walk, not the concept page. ## Before you begin Confirm four things. Your role is Admin or Owner in Tale — the **Integrations** panel is hidden below that. Meetily is running and producing transcripts in a format Tale accepts (Markdown, plain text, or VTT). The Meetily host is reachable from `tale-platform` on its webhook or shared-folder path. And the target project already exists in Tale with a Knowledge Base attached — the integration writes _into_ a Knowledge Base, it does not create one. ## Step 1 — Pick a delivery path Meetily can hand transcripts to Tale in two shapes, and they have different operational properties. The pick locks in how the rest of the walk reads. The **webhook** path has Meetily POST each finished transcript to a Tale ingestion endpoint as soon as the meeting ends; the transcript is in the Knowledge Base within seconds of the meeting closing. The **shared folder** path has Meetily write transcripts as files into a directory the Tale platform polls every minute; latency is up to a minute but the path needs no public URL and survives Meetily restarts without retry logic. Pick webhook when both services run in the same network and you want fast indexing; pick shared folder when Meetily runs on a workstation that wakes irregularly or when the operations team prefers a file-based audit trail. ## Step 2 — Create the ingestion endpoint or folder in Tale Tale needs to know where transcripts will land and which project they belong to. Without this binding, transcripts arrive but no Knowledge Base claims them. Open **Settings > Integrations**, click **Add integration**, and pick **Meeting transcripts**. Pick the project from the dropdown — the Knowledge Base the project uses is the destination. Pick the delivery path you chose in Step 1. If you picked webhook, Tale generates a URL of the shape `https://<your-host>/integrations/transcripts/<token>` and shows it once. Copy the URL; it doubles as the bearer credential, so treat it like a secret. If you picked shared folder, Tale prompts for the path on disk that `tale-platform` should watch (typically `/data/transcripts/<project-slug>`). Create the directory on the host, give it group ownership matching the `tale-platform` container user, and confirm. ## Step 3 — Point Meetily at Tale Meetily now needs to know where to deliver each transcript. The settings live in Meetily's own config. For the webhook path, open Meetily's settings and add a webhook destination with the URL from Step 2. Pick the transcript format — Markdown is what reads best inside a Tale document preview, but VTT and plain text both index correctly. For the shared-folder path, set Meetily's transcript-output directory to the path you created in Step 2. Make sure Meetily writes one file per meeting, named with the meeting title and timestamp. End a short test meeting in Meetily and watch the Tale Integrations panel. The integration row shows a **Last delivery** timestamp that updates within a minute (folder mode) or a few seconds (webhook mode). ## Step 4 — Verify the document lands and indexes The proof the wiring works is one transcript visible in the Knowledge Base as a searchable document. Without this step you do not know whether Tale received the file _and_ indexed it. Open the target project, navigate to its Knowledge Base, and look for the new transcript at the top of the document list. Click into the preview — the transcript renders as a document with the meeting title as the document name and the meeting date as the document's created-at. Wait for the indexing badge to clear (a few seconds for a short transcript, up to a minute for a long one), then run a search for a name or a phrase you remember from the test meeting. The transcript should be the first result with the phrase highlighted. If the document is there but the indexing badge stays orange, indexing is behind — the [Troubleshooting](/self-hosted/operate/observability/troubleshooting) page names the symptoms. ## Privacy notes The integration crosses one network in each direction and the data shape matters. - **Meetily → Tale.** The transcript body crosses, plus the meeting title, the timestamp, and any speaker labels Meetily attached. Audio does not cross — Meetily transcribes locally and only the text is delivered. The webhook path uses HTTPS with the bearer token in the URL; the folder path uses a filesystem path with no network at all. - **Tale → Meetily.** Nothing. The integration is one-way; Tale never calls back into Meetily. - **Tale → external services.** The transcript text crosses to whichever embedding provider is bound to the Knowledge Base. If the embedding provider is a local one (Ollama, LM Studio, vLLM via [Connect a local LLM provider](/tutorials/admin/connect-local-provider)), no transcript text leaves the host. If the embedding provider is OpenAI, Anthropic, or another hosted endpoint, the transcript text is sent to that endpoint for vectorisation per the provider's data-handling policy. When transcripts contain content the org cannot send to a cloud provider, the supported pattern is to bind the project's Knowledge Base to a local embedding model. The provider-bind happens in the Knowledge Base settings, not in this integration. ## Where this fits The meeting-transcription integration is the cleanest example of "Tale indexes what your other tools already produce" — no copy-paste, no manual upload, no extra step in the meeting workflow. The natural next reads are [Knowledge Base](/platform/knowledge/overview) for what the indexed transcript can then be used for inside an agent, and [Connect a local LLM provider](/tutorials/admin/connect-local-provider) when the privacy section above pushes you toward keeping the embedding step on-host. # Install the Outlook add-in Source: https://tale.dev/docs/tutorials/admin/office-add-in The Outlook add-in surfaces a Tale sidebar inside Outlook on the web, desktop, and mobile. From the sidebar a member picks an agent, drops the open mail thread in as context, and gets a draft reply back without switching apps. This walk is for an Admin rolling the add-in out across an org; it covers the manifest deploy, the sign-in, and the verification. You need an Admin role in Tale, a Microsoft 365 tenant where you can manage Integrated Apps, and a Tale instance reachable from the Microsoft 365 cloud. Cloud orgs are reachable by default; self-hosted instances need a public HTTPS URL. ## Before you begin Confirm three things on the Microsoft side: you are a Global Administrator (or have the Exchange Admin role with Integrated Apps), centralised deployment is enabled for your tenant, and the mailbox you will test with has not blocked add-ins via mailbox policy. On the Tale side, open **Settings > Integrations** and check that **Microsoft 365** is listed — that is where the add-in publishes the manifest URL. ## Step 1 — Get the manifest URL from Tale The add-in talks to Tale through a manifest XML the Microsoft 365 admin centre hosts. Tale generates the manifest per instance so the sidebar points at your URL, not at a shared multi-tenant endpoint. Open **Settings > Integrations > Microsoft 365** and copy the **Add-in manifest URL** the panel shows. You should see a URL ending in `/integrations/office/manifest.xml`. Open it in a new tab to confirm it returns XML and not an HTML error page — if it errors, your instance is not reachable from outside or the integration is disabled. ## Step 2 — Deploy through the Microsoft 365 admin centre The manifest is what tells Microsoft 365 which mailboxes can see the sidebar and what URL to load it from. Centralised deployment is the supported path; user-by-user side-loading works but does not survive a mailbox migration. Open the Microsoft 365 admin centre, navigate to **Settings > Integrated apps > Upload custom apps**, choose **Office Add-in** and **Provide link to manifest file**, and paste the URL from Step 1. Pick the rollout audience — the whole tenant, a security group, or a specific list of users. Submit. Microsoft confirms the deployment with a green banner; the rollout typically reaches mailboxes within an hour, sometimes a few hours on a large tenant. ## Step 3 — Sign in from the sidebar Open Outlook as a user in the rollout audience, click any mail message, and look for the Tale icon in the message ribbon. Clicking it opens the sidebar; on first open it asks the user to sign in with their Tale account. The sign-in is OAuth through the Tale instance — same identity provider as the web app. After sign-in the sidebar lists the user's available agents. Picking one and clicking **Draft reply** pulls the open mail thread in as context and streams a reply into the sidebar. The user reviews, edits, and clicks **Insert** to drop it into the Outlook compose pane. ## Where this fits The add-in is the lightest path to "Tale where your members already work" — no portal switch, no copy-paste. The sidebar is a thin shell around the same agents you publish in [Create an agent](/platform/agents/create); changes to the agent's instructions, knowledge, or tools land in the sidebar on the next request. For the broader integration story — Slack, Gmail, custom MCP servers — see [Integrations overview](/platform/integrations/overview). If you operate a self-hosted instance and the manifest URL is unreachable from Microsoft 365, the [Linux server](/self-hosted/install/linux-server) page covers the public-HTTPS prerequisite. # Build a custom tool Source: https://tale.dev/docs/tutorials/developer/build-a-custom-tool A custom tool is a function you write that an agent's model can call by name. You declare the input schema and the return shape; Tale handles serialisation, the tool-call card in the chat, and the result hand-back to the model. This walk takes a fresh custom tool from "I have a function in mind" to "the agent calls it from a chat" on a single instance. You need a Developer role in the org and access to the **Settings > Custom tools** panel; everything else is in the UI. The underlying concept lives in [Agent tools](/platform/agents/tools); the developer-facing surface — schemas, transport, errors — is the focus here. ## Before you begin Confirm two things. First, your role is at least Developer — the panel is hidden below that. Second, you have an agent you can edit; if not, create one through [Create an agent](/platform/agents/create) before continuing. The walk uses a single-input, single-output tool called `lookup_order` that takes an order ID and returns a status string — the smallest shape that exercises the schema, the call, and the result rendering. ## Step 1 — Define the tool in Custom tools The first move is registering the tool name and its JSON Schema. The schema is what the model sees; without a schema the model has no idea what arguments to emit, and the call never happens. Open **Settings > Custom tools** and click **New tool**. Give it a name (`lookup_order`), a one-sentence description (`Look up the status of an order by ID`), and a JSON Schema for the input: ```json { "type": "object", "properties": { "orderId": { "type": "string", "description": "The order ID, e.g. ORD-12345" } }, "required": ["orderId"] } ``` Save. The tool is now registered in the org's custom-tool registry; no agent uses it yet. ## Step 2 — Wire the implementation A registered tool with no implementation returns an error to the model. Tale exposes two implementation modes: an inline sandbox script (Python or JavaScript, run inside Tale's sandbox), and an outbound HTTPS call (Tale POSTs the arguments to your endpoint, you return JSON). Pick the HTTPS mode for this walk — it is the shape you reach for in production. In the tool's detail panel, set: - **Endpoint URL** — `https://your-api.example.com/lookup-order` - **Method** — `POST` - **Auth header** — a bearer token from your secrets manager Tale POSTs `{ "orderId": "..." }` to your endpoint; your endpoint returns `{ "status": "shipped", "carrier": "DHL", "eta": "2026-06-01" }`. Save. The custom tool is wired. ## Step 3 — Attach the tool to an agent A wired tool is invisible to agents until one of them is given permission to call it. Open the agent you want to extend, click **Tools**, scroll to **Custom tools**, and toggle `lookup_order` on. Save the agent. Open a chat with the agent and ask "what is the status of order ORD-12345". The chat shows a collapsed `lookup_order` tool-call card between your message and the reply; expanding it shows the arguments the model emitted (`{ "orderId": "ORD-12345" }`) and the JSON your endpoint returned. The model then writes the reply using the tool result. ## Where this fits A custom tool is the seam between an agent and your domain — order lookup, internal search, calculator, anything an off-the-shelf integration does not cover. The schema is what the model uses to decide whether to call, so spend the time to write a tight description and only the fields you need. For tools you want to share across orgs, see [MCP servers from scratch](/tutorials/developer/mcp-server-from-scratch) — MCP is the protocol for "one tool, many Tale instances". For the conceptual side of what tools do inside an agent, see [Agent tools](/platform/agents/tools). # Call Tale from a script Source: https://tale.dev/docs/tutorials/developer/call-tale-from-a-script Calling Tale from a script is the path you reach for when you want a value back from an agent or a workflow without opening the UI. The Tale API speaks JSON over HTTPS and accepts a bearer token in the `Authorization` header; from there, every endpoint group is a normal REST call. This walk takes you from "I want to script Tale" to a reply streamed into your terminal in one sitting. You need a Developer role (to mint API keys), the URL of your Tale instance, and a shell with `curl`, Python, or Node. The full API surface lives in the [API reference](/develop/api-reference); this page is the smallest end-to-end walk through it. ## Before you begin Confirm three things. Your instance is reachable on HTTPS — open `https://your-host.example.com` and check the dashboard loads. Your role is at least Developer — the **Settings > API keys** entry is hidden for Member and Editor. You have at least one published agent — list agents returns an empty array on a brand-new instance, which makes the smoke test ambiguous. ## Step 1 — Mint an API key The first move is creating an API key scoped to your user. The key is what every script call carries; without it the API returns 401, and you cannot read the key back after creation. Open **Settings > API keys** and click **New key**. Give it a name (`local-script-test`), pick an expiry, and click **Create**. Copy the key the panel shows — Tale displays it once and never again. Store it as an environment variable for the rest of this walk: ```bash export TALE_API_KEY="tk_..." export TALE_BASE_URL="https://your-host.example.com" ``` The key inherits your role; treat it like a password. ## Step 2 — Smoke-test with curl The smallest end-to-end check is listing the agents your key can see. If this works, auth, networking, and the API are all good; if it fails, the failure mode tells you which one is broken. ```bash curl -sS "$TALE_BASE_URL/api/v1/agents" \ -H "Authorization: Bearer $TALE_API_KEY" \ -H "Accept: application/json" | jq ``` A 200 with a JSON body like `{ "agents": [ ... ] }` confirms the round-trip. A 401 means the key is wrong; a 403 means the key is valid but the role is too low; anything else means the instance is unreachable or the path is wrong. Pick an agent ID from the response — you need it for Step 3. ## Step 3 — Call an agent from Python or Node Listing agents is read-only; the useful work happens when you ask an agent to reply. The OpenAI-compatible endpoint is the easiest entry point because existing SDKs work unchanged: ```python from openai import OpenAI import os client = OpenAI( base_url=f"{os.environ['TALE_BASE_URL']}/api/v1", api_key=os.environ["TALE_API_KEY"], ) reply = client.chat.completions.create( model="agt_your_agent_id_here", messages=[{"role": "user", "content": "Summarise the last quarter's revenue."}], ) print(reply.choices[0].message.content) ``` The `model` field is the agent's ID; the agent's instructions, knowledge, and tools run as configured. The same shape in Node uses `openai` from npm with the same `baseURL` and `apiKey`. Streaming works with `stream=True` and Server-Sent Events. ## Where this fits A script is the path you take when the data plane is JSON, not a screen — cron jobs, CI checks, internal portals. The API key carries your role, the OpenAI-compatible endpoint is the lowest-friction shape, and every list endpoint returns the same `{ resource: [...] }` envelope. For inbound triggers — your system POSTing into a Tale workflow — see [Trigger a workflow via webhook](/tutorials/developer/trigger-automation-via-webhook). For the full endpoint inventory and error model, the [API reference](/develop/api-reference) is the single source of truth. # Stand up an MCP server from scratch Source: https://tale.dev/docs/tutorials/developer/mcp-server-from-scratch A Model Context Protocol (MCP) server is a process that exposes a list of tools over a small JSON-RPC protocol. Tale registers an MCP server once at the org level; from then on, every agent whose tools tab includes that server can call its tools. This walk takes a brand-new MCP server from "empty repo" to "called by an agent in a chat" on one Tale instance. You need a Developer role, a host that can run the MCP server (your laptop is fine for the walk; a managed service or container for production), and an HTTPS URL Tale can reach. Cloud orgs reach public URLs by default; self-hosted instances need network access to wherever the MCP server runs. ## Before you begin Confirm two things. You have Node 20 or Python 3.11 installed — the official MCP SDKs target those runtimes. The Tale instance can reach your MCP server's URL — for local development, an `ngrok` tunnel or equivalent works; for production, host the server somewhere with a stable HTTPS endpoint. The conceptual side of MCP in Tale lives in [Agent tools](/platform/agents/tools); this walk is the wiring. ## Step 1 — Scaffold the server The first move is generating the minimum MCP server — one tool, one handler. The official SDK does the protocol plumbing so you only write the tool. ```bash npm create mcp-server@latest hello-tale cd hello-tale ``` Open `src/index.ts` and replace the example tool with one that returns the current time in a named timezone: ```ts server.tool( 'current_time', 'Return the current time in a given timezone', { timezone: z.string() }, async ({ timezone }) => { const now = new Date().toLocaleString('en-US', { timeZone: timezone }); return { content: [{ type: 'text', text: now }] }; }, ); ``` Run the server locally: ```bash npm run start ``` The server listens on `http://localhost:3000/mcp` by default. The scaffold is in place; nothing in Tale knows about it yet. ## Step 2 — Expose it on HTTPS MCP servers Tale can call need an HTTPS URL with a valid certificate. For local development, point an `ngrok` tunnel at port 3000 and copy the public URL the tunnel prints. For production, host the server behind your normal ingress — Caddy, Nginx, a managed function, anything that terminates TLS. Verify the public URL responds to a health check: ```bash curl -sS "https://abcd.ngrok.app/mcp/health" ``` A 200 confirms reachability. A 502 or timeout means the tunnel is not forwarding; restart it or check the firewall. ## Step 3 — Register the server in Tale A reachable MCP server is invisible to Tale until you register it. Open **Settings > Integrations > MCP servers** and click **New server**. Fill in: - **Name** — `Hello Tale time` - **URL** — the public HTTPS URL from Step 2 (e.g. `https://abcd.ngrok.app/mcp`) - **Auth** — bearer token if your server requires it, none for the walk Click **Save**. Tale calls the server's `list_tools` method to discover the tool inventory; the panel shows `current_time` with its description. The server is now registered org-wide. ## Step 4 — Attach the server to an agent and call the tool A registered server is reachable only by agents that opt in. Open any agent, click **Tools > MCP**, toggle **Hello Tale time** on, and save. Open a chat with the agent and ask "what time is it in Tokyo right now". The chat renders a `current_time` tool-call card; expanding it shows `{ "timezone": "Asia/Tokyo" }` and the timestamp your server returned, and the agent's reply uses the timestamp. ## Where this fits An MCP server is the right shape when a tool needs to live outside Tale — code your team owns, a service in another network, a third-party API you wrap. Custom tools in [Build a custom tool](/tutorials/developer/build-a-custom-tool) are the right shape when the tool is one-off and lives inside one org's settings. For the bigger picture of how tools widen what an agent can do, see [Agent tools](/platform/agents/tools). For wiring an integration that wraps a third-party API instead of your own code, [Integrations overview](/platform/integrations/overview) is the next read. # Trigger a workflow via webhook Source: https://tale.dev/docs/tutorials/developer/trigger-automation-via-webhook A webhook trigger turns a Tale workflow into something an external system can fire by POSTing JSON. Tale recognizes the token in the URL, stores the idempotency key, and kicks off a run — the same shape any incoming webhook needs to be safe to retry. This walk takes a new workflow from "I want to fire it from outside" to "an order event posts and the workflow runs" on a single instance. You need a Developer role in the org, an existing workflow (or use the empty starter), and a shell with `curl`. The full webhook contract — signing, idempotency, retries — lives in [Webhooks](/develop/webhooks); this walk is the smallest end-to-end use of the inbound side. ## Before you begin Confirm two things. The workflow you will trigger exists and is published — drafts cannot be triggered. Your role is at least Developer — adding webhook triggers is gated to Developer and above. If you do not have a workflow yet, the canonical small one is "log the payload to the execution record"; create it through [Workflow with approvals](/tutorials/editor/workflow-with-approvals) and remove the approval step for this walk. ## Step 1 — Add a webhook trigger to the workflow The first move is binding a webhook trigger to the workflow. Without a trigger, the workflow is only callable from the UI; with one, it gets a URL any system can POST to. Open the workflow's **Triggers** tab and click **Add webhook**. Tale mints a unique **Webhook URL** with the credential embedded as a token in the path — there is no separate key or Authorization header. Save the URL when it is shown: anyone holding it can fire the workflow, so treat the whole URL as a secret. Deleting the webhook revokes it. ```bash export TALE_TRIGGER_URL="https://your-host.example.com/api/workflows/wh/<token>" ``` ## Step 2 — POST a payload from curl The webhook URL is a normal POST endpoint. The body becomes the input of the workflow's first step; an `Idempotency-Key` header makes retries safe — a replay returns the earlier run instead of starting a new one. ```bash curl -sS "$TALE_TRIGGER_URL" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: order-12345" \ -d '{ "orderId": "12345", "amount": 199.0 }' ``` A 200 returns `{ "status": "accepted", "workflowSlug": "..." }`. The workflow is now running asynchronously; open the workflow's **Executions** tab and you should see a run in progress with your payload as the trigger input. A 404 means the token in the URL matches no webhook; a 403 means the webhook is disabled or the workflow is no longer installed; a 429 means the caller's IP hit the rate limit. ## Step 3 — Make retries safe with idempotency External systems retry on timeouts and 5xx errors; without idempotency, a retry double-fires the workflow. The `Idempotency-Key` header from Step 2 is the fix: Tale remembers the key per organization and answers a retry with `{ "status": "duplicate", "executionId": "..." }` — the original run — instead of firing again. Test it by re-running the same curl above. The response carries the first call's `executionId`, and the workflow's **Executions** tab still shows one run. Change the key to `order-12346` and curl again — that one fires a second run. The source system must use a stable, deterministic key per logical event. A common pattern is `<event-type>-<event-id>`; never use a random UUID generated at retry time, since each retry would mint a new run. ## Where this fits Webhook triggers are the inbound half of Tale's workflow API — the seam your CRM, your order system, or your monitoring tool POSTs into. Use them for "this happened in our world, please run a Tale workflow about it"; reach for the [API reference](/develop/api-reference) when you want a synchronous reply instead. For the outbound half — Tale POSTing to your URL when a Tale event happens — and for the full signing and retry contract, see [Webhooks](/develop/webhooks). The workflow-side configuration of the trigger lives on the [Workflow triggers](/platform/automations/triggers) page. # Build an agent with knowledge Source: https://tale.dev/docs/tutorials/editor/agent-with-knowledge An agent with knowledge is the shape you reach for when the model needs to answer from specific documents — your product manual, your policies, last quarter's call notes — not from whatever it learned during training. The agent retrieves chunks from the bound sources at reply time and cites them. This walk takes a fresh agent from "I want it to know my docs" to "the reply cites the right document" on one instance. You need an Editor role, the ability to upload documents to the knowledge base, and roughly three documents to bind. The conceptual side lives in [Agent knowledge](/platform/agents/knowledge); this walk is the end-to-end mechanic. ## Before you begin Confirm three things. Your role is at least Editor — agent editing is gated to Editor and above. You have at least three documents on hand to upload (PDFs, DOCX, Markdown — anything the knowledge base accepts). You have a provider configured so the agent can run — without one, the test reply at the end fails on the model call. ## Step 1 — Upload documents to the knowledge base The first move is putting the documents inside Tale's knowledge base. Documents that are not in the knowledge base cannot be bound; the agent only sees sources it can name. Open **Knowledge > Documents** and click **Upload**. Drag the three documents in, give them sensible titles, and wait for the status column to show **Ready** for each. The status walks through `uploaded → processing → ready`; processing chunks the document and computes embeddings. A typical PDF reaches **Ready** in a minute or two. If a document sticks on `processing` for more than five minutes, open its row to see the error — the most common cause is an unsupported format (image-only PDFs, password-protected files) or a file larger than the org's upload limit. ## Step 2 — Create the agent A bound document goes on an agent, so the agent has to exist first. Open **Agents > New agent** and fill in the four knobs as a baseline: - **Name** — `Docs Q&A` - **Instructions** — `You answer questions strictly from the bound documents. If you cannot find the answer in the documents, say so explicitly. Cite the document title for every claim.` - **Tools** — toggle **RAG** on; everything else off - **Model** — pick whatever default the org uses Save and publish. The agent now exists but has no knowledge — it will refuse every question because it cannot find any source. ## Step 3 — Bind the documents The binding is the seam that gives the agent retrieval access to a subset of the knowledge base. Open the agent's **Knowledge** tab and click **Agent knowledge**. Pick the three documents from Step 1 and save. The Knowledge tab now lists three bound sources. The agent's RAG tool will retrieve only from those three; nothing else in the knowledge base is reachable from this agent, even other documents in the same library. ## Step 4 — Ask a question and check the citation Open a chat with `Docs Q&A` and ask a question one of the documents answers. The reply streams in with citations inline — hovering shows the document title, clicking opens the document at the cited chunk. Ask a question none of the documents covers; the agent should refuse explicitly per the instruction, not invent an answer. If the agent invents an answer anyway, the instructions are not strict enough — add an explicit refusal case ("If you cannot find the answer in the bound documents, respond with exactly: 'I could not find this in the bound documents.'") and republish. ## Where this fits The four moves above are the canonical "agent that answers from your docs" build: upload, create the agent with RAG on, bind, verify with a citation. The same shape scales — bind ten documents instead of three, add a website or a customer record, swap the model. The bindings, not the model, are what makes the agent yours. For the conceptual side of how retrieval composes with the agent's other knobs, see [Agent concepts](/platform/agents/concepts). For the wider knowledge-base story — Customers, Products, Vendors, Websites — see [Knowledge overview](/platform/knowledge/overview). # Hand work to a worker Source: https://tale.dev/docs/tutorials/editor/delegate-between-agents When a request deserves its own focused context — cited research, bulk extraction, a long draft — the assistant spawns a **worker**: an ephemeral agent composed for exactly that task, with exactly the capabilities the assistant grants it from its own set. There is nothing to configure; this walk runs one research job end to end and shows you how to read the job card. The conceptual side (capability subsets, budgets, methodologies) lives in [Agent workers](/platform/agents/delegation). ## Before you begin You need a chat-capable agent (the built-in Assistant works as-is) on a model with tool-calling support. For live web sources, connect a search integration such as Tavily under **Settings > Integrations** — without it the worker falls back to plain web fetching and says so in its result. ## Step 1 — Ask for something worth a worker Open a chat with `Assistant` and ask for open-ended, citable work, for example: `Research the current state of solid-state batteries — market, key players, cited sources.` A quick factual question won't (and shouldn't) spawn anything; workers are for tasks that benefit from isolation. ## Step 2 — Watch the job card The assistant calls `spawn_agent` and a **job card** appears under its turn: the worker's name, a live status, and the worker's own progress checklist filling in as it plans and works through sub-questions. The card never blocks the composer — you can keep typing while the worker runs. If the card shows a "skipped" note, the assistant requested something outside its own grants (say, an unconnected integration); the run continues with what remains, and the note tells you what to connect for next time. ## Step 3 — Read the result and the transcript When the job finishes, the assistant folds the worker's deliverable into its reply — for research, a conclusion, key points with inline citations, and sources. On the card, expand **worker activity** to see the full transcript: every search, every tool call, and the worker's reasoning. That transcript is the audit trail you point at when someone asks what the agent actually did. ## Step 4 — When something goes wrong A worker that runs out of time or hits an error ends with a visible status on the card — `timed out` or `failed` — with its partial progress intact. The assistant reports what it got and continues itself where it can. Nothing fails silently: if the worker needed input only you can give, the assistant asks you directly. ## Where this fits One request, one worker, one card is the smallest useful shape. The same mechanics scale to several workers in a turn — each gets its own card, its own progress, and its own transcript. For fixed stages with approvals or scheduling between them, reach for a [workflow](/platform/automations/concepts) instead. # Build your first agent Source: https://tale.dev/docs/tutorials/editor/first-agent-end-to-end A first agent is the smallest useful thing in Tale: instructions plus a model, sometimes with one tool or one document bound. This walk turns the four knobs in order — instructions, knowledge, tools, model — and leaves you with a published agent that answers a real question in a chat. The shape generalises: every agent you build later is the same four moves with different choices. You need an Editor role and a configured chat-tagged model on the org's provider. The conceptual side lives in [Agent concepts](/platform/agents/concepts); this walk is the end-to-end mechanic. ## Before you begin Confirm three things. Your role is at least Editor — agent editing is gated to Editor and above. The org has a provider configured and at least one chat-tagged model on it; without that, the test reply at the end fails on the model call. You have a question in mind the agent should answer — pick something narrow enough that a paragraph of instructions can frame it, like "summarise an inbound customer message into one sentence plus a recommended next action". ## Step 1 — Write the instructions Instructions are the system prompt — the prose that frames every reply. The first knob is the one most people overshoot. Open **Agents > New agent** and set: - **Name** — `Triage assistant` - **Instructions** — `You read a customer message and produce two lines. Line one: a one-sentence summary in plain English. Line two: a recommended next action — reply, escalate, or close. If the message is blank or off-topic, refuse and say so.` Save as a draft for now; publishing comes after the other knobs. Short, opinionated, concrete instructions outperform long ones — keep the rules under a paragraph. ## Step 2 — Decide on knowledge Knowledge is what the agent can reference at reply time. For this first agent, leave Knowledge empty: the job is reading the message, not retrieving anything. The Knowledge tab stays untouched. If you wanted to add knowledge later — say, an escalation matrix the agent should consult — you would upload the document, open the agent's **Knowledge** tab, and bind it. The full mechanic is in [Agent with knowledge](/tutorials/editor/agent-with-knowledge). ## Step 3 — Pick the tools Tools are what the agent can do beyond reply with text. For triage, no tools are needed: the agent reads input and writes output. Open the **Tools** tab and leave every toggle off. Every tool you grant widens the trust boundary; keep the list short. If the agent should write the recommended action back to a CRM, you would toggle the corresponding integration tool on later — but not before the text-only version works. ## Step 4 — Pick the model and publish Open the **Model** tab and pick the org default for the primary; set a smaller model as the fallback so the agent still runs when the primary is rate-limited. Save, then click **Publish**. The agent is now visible in chat to everyone with the right role. Open a chat with `Triage assistant` and paste in a real customer message. The reply should land in two lines per the instructions — a one-sentence summary and a recommended action. If the format drifts, tighten the instructions and republish; this is the loop you spend the most time in. ## Where this fits Four knobs, one published agent, one verified reply: the same shape every agent you build later follows. The next walks specialise on one knob each — [Agent with knowledge](/tutorials/editor/agent-with-knowledge) on the second knob, [Hand work to a worker](/tutorials/editor/delegate-between-agents) on the third. For the concept page that names the four knobs and the trade-offs between them, see [Agent concepts](/platform/agents/concepts). For versioning and rollback once the agent matures, see [Agent versions](/platform/agents/versions). # Build a workflow with an approval Source: https://tale.dev/docs/tutorials/editor/workflow-with-approvals A workflow with a human decision in the middle is the shape you reach for when the work has a draft, a review, and an action — and you want a person between the draft and the action. The run pauses as **Waiting for input** until someone answers; the next step only fires on a green light. This walk builds a daily-summary workflow that way, and you meet both human gates on the road: approving the AI editor's proposal, and answering the paused run. You need an Editor role and one agent that produces a draft (the first useful agent from [Build your first agent](/tutorials/editor/first-agent-end-to-end) works fine). The conceptual side lives in [Automation concepts](/platform/automations/concepts) and [Approval concepts](/platform/approvals/concepts); this walk is the end-to-end mechanic. ## Before you begin Confirm three things. Your role is at least Editor — workflow editing is gated to Editor and above. You have a draft-producing agent ready to call; without it the draft step has nothing to invoke. And you can answer the review yourself — the paused run waits for a human, and in this walk that human is you. ## Step 1 — Open a workflow in the editor Workflows live inside the automation they power: open the automation and its **Editor** tab is the workflow, with the step graph on a canvas. For this walk, open a workflow you own or one your org's task-ops pack provisioned — anything you are allowed to edit works, because the AI editor builds the new definition for you either way. ## Step 2 — Describe the workflow to the AI editor Toggle the **AI editor** on the canvas toolbar and describe the whole shape in one message: > Every weekday at 08:00, have the <your agent> agent summarise yesterday's unread customer messages into one paragraph, then ask a human to review the draft, and only send the approved text to the team channel. The AI editor answers with a proposal card — **Create workflow** with the step count, or **Update workflow** when it reworks the one you opened. Nothing touches the definition while the card is pending: expand it, check the steps it lists — an **LLM** step for the draft, the review pause, the send — and approve it. The change is applied and versioned like any manual save. ## Step 3 — Attach the schedule Switch to the **Triggers** tab and click **Add schedule**. Pick the **Every day** preset and adjust the cron to weekdays (`0 8 * * 1-5`) — or describe the timing in plain language and click **Generate** to let the AI write the cron. **Workflow variables** pre-fills from the workflow's input schema; leave it as proposed. The row appears with an **Active** toggle already on. ## Step 4 — Run it and answer the review Back in the editor, open **Test workflow**, paste the input JSON the panel proposes, and click **Execute**. The panel mirrors the run step by step: the draft step fires, then the run pauses — **Waiting for input** — and the review arrives as a form card holding the draft. Fill it and click **Submit response** to approve, or **Reply differently** to push back in free text; the run resumes with your answer and the send step fires. Open the **Executions** tab and expand the run: the journal shows one entry per step — the draft the agent produced, who answered the review and what, and the send with its output. That journal is the audit trail; the same record appears for every future scheduled run. ## Where this fits Draft, decide, act — with the decision a human's — is the smallest useful workflow-with-approval, and you built it without placing a single step by hand: the AI editor proposed, you approved, the run asked, you answered. The same shape scales — add a second review before a destructive step, or let [Approvals in workflows](/platform/automations/approvals-in-workflows) show you the other gates around a workflow. For the vocabulary behind definition, trigger, and execution, [Automation concepts](/platform/automations/concepts) is the page this walk assumed. # Chat effectively Source: https://tale.dev/docs/tutorials/member/chat-effectively Chatting effectively in Tale is not about clever prompts; it is about giving the chat enough context for the model to read your intent the first time. Five small habits — picking the right agent, picking the right model, attaching only what matters, asking inside a scope, reading the citations — turn the average reply from "thanks for the wall of text" into "exactly what I needed". This page walks the habits in order on a fresh chat. You need a Member role (the floor for chat) and one published agent on the org you can address. The conceptual side lives in [Chat basics](/platform/chat/basics); this walk is the daily-driver mechanic. ## Habit 1 — Pick the agent before the first message The agent is the lever with the highest payoff per click. The default Assistant is a blank canvas; an agent with knowledge bound, tools enabled, and a tuned voice will out-answer it for any non-generic question. Open the agent picker in the composer and pick the agent whose scope matches your question — Support, Sales, Research — before typing. If no agent fits, leave the Assistant on; do not pick a wrong-fit agent for "close enough". A wrong-fit agent often refuses or veers off the bound knowledge. ## Habit 2 — Pick the model to match the message The model picker beside the agent picker lists the agent's allowed models. **Auto** is fine most of the time; switch when the message changes shape. A long reasoning question wants a larger model; a quick lookup wants a smaller, faster one. A message with an image needs a vision-capable model — without that, the image is silently dropped. The model picker shows the tag (`Chat`, `Vision`, `Image`, `Embedding`) next to each name; match the tag to the message. ## Habit 3 — Attach only what the agent needs Attachments are tempting to overuse. A 200-page PDF as a single attachment fills the context budget and dilutes the answer; the relevant pages excerpted into the prompt outperform the whole file. If you do attach a long document, ask a specific question against it ("what does page 12 say about refunds?") rather than an open one ("tell me everything"). For files you will reference often — a price list, a policy document — upload them into the [Knowledge](/platform/knowledge/documents) section and bind them to an agent. Once bound, every chat with that agent has them on tap without re-uploading. ## Habit 4 — Ask inside the agent's scope Every agent has an implicit scope from its instructions and bound knowledge. Asking a billing agent about marketing strategy gets you a polite refusal at best, a hallucination at worst. The cheap fix: read the agent's bio at the top of the picker before you ask — it names the scope. If your question is outside the scope, switch agents. ## Habit 5 — Read the citations and follow them When the reply includes citations (the small inline links), open one. The citation points to the chunk of the source the agent quoted from; reading it confirms the agent did not paraphrase past what the source actually says. The two-minute habit of opening one citation per reply catches the small subset of replies where the agent overreached. ## Where this fits Five habits, one chat, the same loop every time you open the Chat tab. The habits compound — picking the right agent makes the right model obvious; the right model makes the citations trustworthy; the citations close the loop. For the surface these habits live on, see [Chat basics](/platform/chat/basics). For the file side — what gets pasted verbatim, what gets indexed — see [Attachments](/platform/chat/attachments). # Use projects to bundle files and chats Source: https://tale.dev/docs/tutorials/member/use-projects A project is what you reach for the second time you find yourself pasting the same context into a chat. It bundles files, instructions, and chats around one body of work — a customer, a launch, a long investigation — so every new conversation starts with the context already loaded. This walk takes a fresh project from "I keep re-uploading the same brief" to "every chat inside this project already knows the brief" on one instance. You need a Member role (the floor for creating projects) and three or four files you keep referencing. The conceptual side lives in [Project concepts](/platform/projects/concepts); this walk is the end-to-end mechanic. ## Before you begin Confirm two things. Your role is at least Member — project creation is gated to Member and above. You have three to four files that recur across the chats you have been having — a brief, a transcript, a price list, a policy. Those become the project's working set. ## Step 1 — Create the project The project is the container the rest of the pieces live in. Open **Projects > New project** and set: - **Name** — `Acme account` (or whatever names the body of work) - **Description** — one sentence on what the project is for - **Members** — leave it private for now; you can add teammates after the first chat works Save. The project appears in the sidebar; clicking it opens an empty project view with tabs for Knowledge, Threads, Agents, and Instructions. ## Step 2 — Upload the files once The project's files are visible to every chat inside the project, so this upload happens once and pays back on every later chat. Open the **Knowledge** tab and drag in the three or four files you confirmed in the prerequisites. Each file lands in the project's storage and indexes the same way a knowledge-base document does. Once the status is **Ready**, the files are reachable by any chat started inside the project. ## Step 3 — Add project instructions Project instructions frame every chat in the project. They compose with the agent's own instructions: the project frames the work, the agent frames the reply. Open the **Instructions** tab and set: `You are working on the Acme account. The contract and the call notes in the Knowledge tab are the source of truth; cite them when you make a claim. The customer's voice is conservative — drafts should not promise dates we have not confirmed.` Save. Every new chat in the project will now run with this preamble in addition to the agent's own instructions. ## Step 4 — Start a chat and verify the context follows Open the **Threads** tab and click **New chat**. Pick an agent — the default Assistant is fine for the first run — and ask a question one of the project's files answers (`What does the contract say about the renewal clause?`). The reply should cite the contract; the citation opens the file from the project's Knowledge tab, not from the org-wide library. If the agent answers without citing, the project's files were not retrieved — usually because the chosen agent has no retrieval tool enabled. Switch to an agent with RAG on, or enable it on the Assistant for project use. ## Where this fits A project with files, instructions, and threads is the smallest useful unit of shared context in Tale. The same shape scales — add members so a team works the project together, add a project-scoped agent so the voice is locked in, archive the project when the work ships. For the deeper model of what a project is and when to reach for one, see [Project concepts](/platform/projects/concepts). For project-scoped agents, see [Project agents](/platform/projects/project-agents). # Tutorials Source: https://tale.dev/docs/tutorials/overview Tutorials are end-to-end walkthroughs: each takes a fresh instance from "I want to do X" to a working, verified result. They assume you have the right role and a running workspace; the concept pages under [Platform](/platform) explain the mental model, tutorials show the mechanic from start to finish. If you have not walked a [get-started journey](/get-started/quickstart) yet, start there — tutorials build on the day-one moves those cover. ## Pick by role <CardGroup cols="2"> <Card title="Member tutorials" icon="message-circle" href="/tutorials/member/chat-effectively"> Chat effectively, work in projects, hold voice conversations. </Card> <Card title="Editor tutorials" icon="bot" href="/tutorials/editor/first-agent-end-to-end"> Build a first agent end to end, bind knowledge, delegate between agents, ship workflows with approvals. </Card> <Card title="Developer tutorials" icon="terminal" href="/tutorials/developer/call-tale-from-a-script"> Call Tale from a script, trigger workflows via webhooks, build custom tools, stand up an MCP server. </Card> <Card title="Admin tutorials" icon="shield" href="/tutorials/admin/office-add-in"> Install the Office add-in, wire meeting transcription, connect a local provider. </Card> </CardGroup> ## Where this fits Tutorials cite the feature references under [Platform](/platform) for the conceptual scaffolding; once you have walked one, the page worth re-reading is the underlying concept page. If you do not know which tutorial to pick, [Build your first agent](/tutorials/editor/first-agent-end-to-end) is the closest thing to a "hello world" for the product — most product capabilities you eventually touch appear in it. # Privacy policy Source: https://tale.dev/docs/legal/privacy This policy describes how Tale handles personal data when you use Tale Cloud, the docs site, the marketing site, or the in-product features. The shape is the same whether you are an end user, an org admin, or a visitor reading the docs — different surfaces collect different data, and each is named below. The policy applies to Tale Cloud; self-hosted instances are operated by the organisation that runs them and the controller is that organisation, not Tale. Read this when you want to know what Tale stores about you, why, and how to remove it. Come back when policy changes — material changes are announced on the status page and emailed to org Owners. ## What we collect Three buckets of data exist, each with its own retention rule: - **Account data.** Name, email, organisation, role, and the credentials you use to sign in. Required to operate the service. - **Product data.** Everything you put into the product — agents, workflows, documents, conversations, knowledge base entries, integration credentials. Stored as long as the parent org exists; deleted on org deletion or via the data-subject request flow. - **Operational data.** Server logs, audit trails, support ticket contents, performance metrics. Tied to your account or org for as long as the data is useful for security, debugging, and compliance — typically up to 90 days for logs and indefinitely for audit trails. We do not sell personal data. We do not use product data to train models — your conversations and documents are not part of any model training set, neither ours nor any provider's, except where you have explicitly enabled a feature that requires it and acknowledged the consent prompt. ## Why we collect it The legal basis for each bucket is one of: - **Contractual necessity.** Account data and the product data you create exist because you asked us to provide the service. We cannot run the platform without them. - **Legitimate interest.** Operational data is collected to keep the platform secure, debug failures, and meet contractual SLAs. - **Consent.** Marketing communications, analytics on the marketing site, and any feature that processes data beyond the contract are consent-based — opt-in, revocable, and recorded. The lawful-basis breakdown per data category lives in the Data Processing Agreement available to enterprise customers on request. ## How long we keep it | Data | Retention | | --------------------- | ------------------------------------------------------------------------ | | Account data | Lifetime of the org plus 30 days after deletion | | Product data | Lifetime of the org; immediate erasure on org deletion | | Documents and uploads | Lifetime of the parent record; soft-deleted records purged after 30 days | | Server logs | 90 days | | Audit logs | Org-configurable floor; default 365 days, no upper bound | | Backups | 30 days, encrypted at rest | Erasure follows the documented data-subject request workflow inside the product — see the in-product governance page for the operator surface. ## Subprocessors Tale Cloud uses a small number of third parties to deliver the service. Each is named, located, and scoped on the [Subprocessors](/legal/subprocessors) page. Material changes to the subprocessor list are announced 30 days before they take effect; org Owners can object via support and have the contract terminated if the new subprocessor is not acceptable. ## Your rights You have the rights granted by GDPR (and the equivalent FADP rights for Swiss data subjects): access, rectification, erasure, restriction, portability, and objection. The mechanics: - **Access and portability.** Export your data from inside the product or via the API; raw exports of org-scoped data are available on request. - **Rectification.** Edit account data and product data inside the product. For data you cannot reach (server logs, audit entries with your user ID), submit a request through support. - **Erasure.** Use the data-subject request workflow under **Settings > Governance > Data subject requests**. Erasure crosses every service that holds the data, including backups via key destruction. - **Restriction and objection.** Submit through support; Tale acknowledges within five business days. Contact: `privacy@tale.dev`. For complaints, the supervisory authority is the data-protection authority of the country in which you reside. ## Where this fits Privacy is the data-handling contract; [Trust and compliance](/cloud/trust-and-compliance) is the operational evidence behind it. If you want to know which third parties touch your data, [Subprocessors](/legal/subprocessors) is the list; if you operate self-hosted, the data never leaves your infrastructure and this policy applies only to your use of Tale's own surfaces (the docs and marketing sites). # Subprocessors Source: https://tale.dev/docs/legal/subprocessors A subprocessor is a third party Tale engages to process customer personal data on its behalf. The list below covers Tale Cloud; self-hosted operators control their own infrastructure and the subprocessor list for those deployments is whichever providers you choose. Material additions are announced 30 days in advance and org Owners are notified by email. Read this when an auditor asks who else touches your data. Come back when a procurement review needs the current vendor list and the location of each. This page mirrors **Appendix A** of the [Data Processing Agreement](https://tale.dev/legal/data-processing-agreement) — both are updated in the same change. The endpoints and data flows of the Tale platform itself are described in the public [API documentation](https://demo.tale.dev/docs). ## No use of customer data for model training Tale does not use customer data — prompts, inputs, outputs, embeddings, audio, images, or any derived artifacts — to train, fine-tune, or improve any AI model. Each AI subprocessor below is contractually bound, via its enterprise or API terms with Tale, to the same. This may only be varied by a separate written opt-in agreement signed by both parties; continued use of the services, in-product toggles, or implicit consent do not count. The binding clause lives at [Data Processing Agreement § 5](https://tale.dev/legal/data-processing-agreement#5-ai-processing--no-use-for-training-or-improvement). ## Current subprocessors Each subprocessor name links to that provider's publicly available DPA (or equivalent terms). Certifications and trust pages are listed in the next section. Platform hosting follows your org's data-residency choice: the first table applies to orgs in the EU/EEA, the second to Swiss orgs. AI calls (LLM inference, audio, and image processing) are processed in the EU/EEA for all orgs — no AI subprocessor Tale engages operates a Swiss region, and none of those calls is processed in third countries such as the USA. ### Orgs in the EU/EEA | Subprocessor (legal entity) | Registered address | Type of service | Place of processing | | ----------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | [Akenes SA (Exoscale)](https://www.exoscale.com/dpa/) | Boulevard de Grancy 19A, 1006 Lausanne, Switzerland | Cloud infrastructure (datacenter): hosting of the Tale Cloud platform — VMs, container runtime, database, and storage. | Germany (Frankfurt region). | | [OpenRouter, Inc.](https://openrouter.ai/privacy) | 169 Madison Avenue, New York, NY 10016, USA | LLM inference (chat, vision, embeddings), audio (speech-to-text and text-to-speech), plus image processing and generation. | European Union (in-region routing via `eu.openrouter.ai`: prompts and responses are processed exclusively within the EU). | ### Swiss orgs | Subprocessor (legal entity) | Registered address | Type of service | Place of processing | | ----------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | [Akenes SA (Exoscale)](https://www.exoscale.com/dpa/) | Boulevard de Grancy 19A, 1006 Lausanne, Switzerland | Cloud infrastructure (datacenter): hosting of the Tale Cloud platform — VMs, container runtime, database, and storage. | Switzerland (Zurich; disaster-recovery replica in Geneva). | | [OpenRouter, Inc.](https://openrouter.ai/privacy) | 169 Madison Avenue, New York, NY 10016, USA | LLM inference (chat, vision, embeddings), audio (speech-to-text and text-to-speech), plus image processing and generation. | European Union (in-region routing via `eu.openrouter.ai`). | For Swiss orgs, platform hosting stays entirely in Switzerland. The AI subprocessor does not offer a Swiss region; those calls are processed in the EU/EEA — every EU/EEA country is on the Swiss Federal Council's adequacy list under Art. 16 FADP, so the transfer requires no additional safeguards. Two notes on the AI subprocessor (OpenRouter): it is engaged only when an AI feature routes a call to it — an org that uses no LLM inference, audio, or image features sends it no data. Model providers reachable through OpenRouter (Anthropic, Google, Meta, Mistral, OpenAI, etc.) are upstream providers of OpenRouter, not Tale's direct subprocessors — the default audio models (Whisper for speech-to-text, gpt-4o-mini-tts for text-to-speech) are OpenAI models reached this way. They operate under OpenRouter's own contractual terms; in-region routing restricts every call to provider endpoints inside the EU. ## Certifications and trust pages Each subprocessor maintains its own security certifications and publishes them on a trust page: - **Exoscale (Akenes SA)** — ISO/IEC 27001:2022, ISO/IEC 27017, ISO/IEC 27018, SOC 2 Type II, PCI DSS v4.0, HDS, BSI C5, TISAX. Trust page: [exoscale.com/compliance](https://www.exoscale.com/compliance/). - **OpenRouter, Inc.** — SOC 2; evidence available through the access-gated trust portal [trust.openrouter.ai](https://trust.openrouter.ai). EU Standard Contractual Clauses apply to transfers outside the EU/EEA. ## Scope of processing For each subprocessor: - **Exoscale (Akenes SA)** runs the Tale Cloud middleware, application state, and supporting infrastructure on VMs and container infrastructure in your org's selected region (Switzerland: Zurich with disaster recovery in Geneva; EU: Frankfurt). Encryption at rest is provided by Exoscale's storage layer. - **OpenRouter** processes prompts and responses for the specific LLM call routed to it (chat, vision, embeddings), audio payloads for speech-to-text and the text input for text-to-speech, plus image prompts and generated images. The data is sent over OpenRouter's in-region routing (`eu.openrouter.ai`) and is not retained by Tale as a separate copy. ## Sub-subprocessors Each subprocessor above engages its own subprocessors (cloud hosting, CDN, secret stores). Their lists are public and linked from each provider's trust page; Tale tracks material changes to the upstream lists through the same 30-day notice mechanism. ## Self-hosted: what changes If you run Tale on your own infrastructure, the only data Tale processes on your behalf is the support and update traffic you opt into (image pulls from the registry, optional telemetry, support tickets). The hosting and model providers in the table above are operated by you, not by Tale; the subprocessor list for your deployment is whatever stack you assemble. ## Where this fits Subprocessors are the vendor inventory; the [Data Processing Agreement](https://tale.dev/legal/data-processing-agreement) is the contract under which they operate (Appendix A is the canonical list); the [Privacy policy](/legal/privacy) is the user-facing policy; [Trust and compliance](/cloud/trust-and-compliance) is the operational evidence. An auditor usually wants the four together — the vendor list, the contract, the policy, and the controls — so the linked pages are mutually consistent and updated in the same change. # Mitgelieferte Automatisierungen Source: https://tale.dev/docs/de/platform/automations/builtin Tale liefert Automatisierungen von Haus aus mit: drei, die ein Postfach in einen geteilten Posteingang verwandeln, ein Bundle, das GitHub-Issues von Anfang bis Ende löst, eine Reihe von Sync- und Pflege-Vorlagen zum Installieren bei Bedarf, und die vorinstallierten Pakete, die Aufgaben-Boards und Erwähnungen für jede Organisation am Laufen halten. Redakteure und Mitglieder nutzen, was eine installierte Automatisierung mitbringt — einen Posteingang-Tab, einen Backlog-Eintrag —, ohne selbst etwas zu installieren; das Installieren ist eine Aktion für Inhaber, Admin oder Entwickler, die [Automatisierungen durchsuchen und installieren](/de/platform/automations/catalog) behandelt. Diese Seite benennt, was jede einzelne tut, und welche Integration zuerst verbunden sein muss. <Frame caption="Der Automatisierungs-Katalog — jede Karte ist eine Installation entfernt; versteckte Paket-Mitglieder und Bundle-Interna bleiben aus der Liste heraus."> ![Der Automatisierungs-Katalog auf dem Tab Alle Automatisierungen, mit Karten für die E-Mail-Automatisierungen und das Bundle GitHub-Issues lösen, jede mit Icon und Beschreibung.](/images/platform/automations-catalog.webp) </Frame> ## Gmail, Outlook und E-Mail über IMAP synchronisieren **Gmail-E-Mails synchronisieren**, **Outlook-E-Mails synchronisieren** und **E-Mails über SMTP/IMAP synchronisieren** sind dieselbe Automatisierung dreimal, je einmal pro Postfach-Art: Jede braucht genau die Integration, die ihr Name sagt, jede installiert dieselbe kanalunabhängige mitgelieferte Ansicht **Posteingang**, und jede bringt den Mail-Sync-Workflow mit, der das Postfach nach Zeitplan in Konversationen holt (ab Werk alle sechs Stunden — auf dem Tab **Auslöser** der Automatisierung enger stellbar). Eine Organisation, die Mail auf mehr als einer Postfach-Art empfängt, installiert mehr als eine davon; jeder Posteingang zeigt nur den Verkehr seines eigenen Postfachs. | Automatisierung | Braucht | Postfach | | -------------------------------------- | --------- | ----------------------------------------- | | Gmail-E-Mails synchronisieren | Gmail | Ein Gmail-Postfach | | Outlook-E-Mails synchronisieren | Outlook | Ein Microsoft-Outlook-Postfach | | E-Mails über SMTP/IMAP synchronisieren | IMAP/SMTP | Jedes private Postfach über IMAP und SMTP | ## Der Posteingang-Tab Jede der drei öffnet auf ihrem Tab **Posteingang**: vier Unter-Tabs — **Offen**, **Geschlossen**, **Spam**, **Archiviert** — jeder eine geteilte Ansicht mit der Konversationsliste links und dem ausgewählten Thread rechts. Eine Konversation zu öffnen füllt die rechte Seite mit ihrem vollständigen Nachrichtenverlauf; solange du keine auswählst, steht dort **Wähle eine Konversation, um Details anzuzeigen**. Der Composer sitzt unter dem Thread im Tab **Offen** — Antworten gehören zu aktiven Konversationen, deshalb sind die anderen drei Tabs reine Leseansichten. Schreib in **Nachricht eingeben** und klick auf Senden; die Antwort geht über das Postfach hinaus, über das die Konversation ankam, mit Empfänger und Betreffzeile aus dem Thread abgeleitet — du adressierst nichts von Hand. **Verbessern** überarbeitet deinen Entwurf mit AI, bevor du sendest. Bei der IMAP-Automatisierung landen auch Antworten, die direkt aus dem Postfach gesendet wurden — egal aus welchem Mail-Programm —, in der Konversation, eingeordnet in den übrigen Verlauf. Der Thread-Kopf trägt die Status-Verben für die ausgewählte Konversation — **Konversation schließen** und **Als Spam markieren** auf einem offenen Thread, **Konversation erneut öffnen** auf einem geschlossenen oder archivierten, **Kein Spam** und das destruktive **Löschen** auf Spam. Mehrere Zeilen in der Liste auszuwählen, bringt dieselben Verben als Massenaktionen hervor. ## GitHub-Issues lösen **GitHub-Issues lösen** ist ein Bundle, keine einzelne Automatisierung: Es installiert über einen gebündelten Assistenten vier versteckte Automatisierungen auf einmal, gebunden an das Projekt, das du wählst, und braucht die GitHub-Integration. Jedes Mitglied übernimmt eine Etappe der Schleife. **GitHub-Issues sichten** bewertet die offenen GitHub-Issues eines Repositorys und schlägt die umsetzbaren als Vorschlag im Projekt-Backlog vor — ein Mensch startet sie von dort. Die vorgeschlagene Aufgabe trägt den Titel `#<Nummer> <Titel>` und übernimmt die Labels des GitHub-Issues. **GitHub-Issues abgleichen** schließt eine Board-Aufgabe, wenn ihr GitHub-Issue geschlossen wurde. Prüft die offenen Aufgaben des Boards selbst und übersieht so keine. Nur Aktualisierung — legt nie neue Aufgaben an. Das gilt unabhängig davon, ob die Lösungskette den Fix gemergt hat oder jemand das Issue direkt auf GitHub geschlossen hat. **GitHub-Pull-Requests erstellen** liefert den PR-Creator-Agent: Sobald ein Mensch eine vorgeschlagene Aufgabe startet, klont er das Repository, öffnet oder übernimmt den Pull Request für das Issue, implementiert den Fix, prüft ihn gegen die eigenen Tests des Projekts und wartet, bis CI grün wird. **GitHub-Pull-Requests prüfen** liefert den PR-Reviewer-Agent: Er testet den Branch des PR-Creators erneut, bestätigt CI, und ein werkzeugloser Richter entscheidet über die Merge-Fähigkeit — genehmigt parkt die Aufgabe bei **In Prüfung** für einen Menschen, der auf GitHub merged; nicht genehmigt schickt sie mit Feedback zurück an den PR-Creator, bis zu einer kleinen Nacharbeits-Obergrenze. An zwei Stellen bleibt ein Mensch in der Schleife: beim Starten einer vorgeschlagenen Aufgabe aus dem Backlog, und beim Mergen des Pull Requests auf GitHub selbst — nichts im Bundle merged in deinem Namen. ## Sync- und Pflege-Vorlagen Acht weitere Automatisierungen liegen im Katalog für den Moment, in dem du sie brauchst. Jede ist ein einzelner Workflow: installieren, auf die eigenen Daten richten — die Sync-Vorlagen fragen ihre Quelle über den Zeitplan ab, den sie anlegen — und danach jederzeit auf dem Tab **Editor** der Automatisierung anpassbar. | Automatisierung | Braucht | Was sie tut | | ------------------------------------------------------ | ------------ | ---------------------------------------------------------------------------------------------------- | | Confluence-Seiten synchronisieren | Confluence | Importiert die Seiten eines Confluence-Bereichs nach Zeitplan in die Wissensbibliothek | | Google-Drive-Dateien synchronisieren | Google Drive | Importiert die Dokumente eines Drive-Ordners in die Wissensbibliothek | | Shopify-Kunden synchronisieren | Shopify | Importiert die Kundinnen und Kunden des Shops in die Kundendaten der Organisation | | Shopify-Produkte synchronisieren | Shopify | Importiert den Produktkatalog des Shops in die Produktdaten der Organisation | | Produktbeziehungen analysieren | — | Durchsucht den Produktkatalog und erfasst Zubehör, Varianten und Ergänzungen | | Dokumente für die Suche indexieren | — | Indexiert neu hochgeladene Dokumente, damit Agenten sie durchsuchen und zitieren können | | Inaktive Konversationen archivieren | — | Schließt Konversationen, die über ihr Inaktivitätsfenster hinaus still geblieben sind | | Mitglieder bei eingehenden Nachrichten benachrichtigen | — | Informiert Mitglieder, sobald eine neue eingehende Nachricht in einer offenen Konversation eintrifft | ## Die vorinstallierten Pakete Auch die Mechanik, die die Boards jeder Organisation antreibt, ist als Automatisierungen gebaut — bei der Erstellung automatisch installiert, im Katalog versteckt, auf dem Tab **Installiert** aber sichtbar wie alles andere. Das **Aufgaben-Paket** startet einen zugewiesenen Agenten, sobald eine Aufgabe bei ihm landet, sichtet unzugewiesene Arbeit, reagiert auf @-Erwähnungen, schickt erledigte Arbeit durch die Prüfung, räumt hängende Läufe auf, setzt SLAs durch und hält abhängige Aufgaben, Unteraufgaben und Archive in Bewegung; seine Geschwister beantworten Diskussions-Erwähnungen und halten OneDrive-Dateien synchron. Jedes ist eine normale Automatisierung — öffne eine, um ihren Workflow auf dem Tab **Editor** zu lesen, unter **Ausführungen** zuzusehen oder unter **Auslöser** einen Auslöser abzuschalten; eine Deinstallation bleibt bestehen und wird nie hinter deinem Rücken rückgängig gemacht. ## Wo das hineinpasst Die Posteingangs-Automatisierungen, das Bundle GitHub-Issues lösen und die Sync-Vorlagen sind das, was heute mitgeliefert wird; eine private Automatisierung, die deine Organisation baut oder hochlädt, taucht im selben Katalog gleich daneben auf. [Automatisierungen durchsuchen und installieren](/de/platform/automations/catalog) deckt die Katalog-Mechanik ab; [Projekt-Backlog](/de/platform/projects/backlog) ist die nächste Lektüre dafür, was mit einer Aufgabe passiert, nachdem GitHub-Issues sichten sie vorgeschlagen hat. # Automatisierungskonzepte Source: https://tale.dev/docs/de/platform/automations/concepts Eine Automatisierung ist die Einheit, zu der Tale greift, wenn eine Aufgabe mehr als ein bewegliches Teil braucht, das zusammengeschaltet werden muss — eine Integration, ein oder mehrere Agents, ein Workflow, manchmal eine eigene Seite —, und du das Ganze lieber in einem Schritt installiert und verbunden haben willst, statt es von Hand zusammenzusetzen. Inhaber, Admins und Entwickler installieren Automatisierungen aus dem Automatisierungen-Katalog; einmal installiert, nutzen Redakteure und Mitglieder, was mitgeliefert wurde — ein Posteingang-Tab, ein Backlog-Eintrag, ein Chat-Agent —, ohne wissen zu müssen, was darunterliegt. Diese Seite benennt die Bestandteile, die eine Automatisierung bündelt, den Workflow, der sie antreibt, und wann eine Automatisierung die richtige Einheit ist statt eines einzelnen Agents. ## Was eine Automatisierung bündelt Das Manifest einer Automatisierung benennt bis zu fünf Arten von Bestandteilen, und die meisten Automatisierungen nutzen nur einen Teil davon. **Integrationen** sind die Anmeldedaten, die ihre Schritte und Agents brauchen — Gmail, GitHub, eine SQL-Datenbank. Eine Automatisierung speichert nie eine eigene Kopie einer Anmeldung; sie benennt nur, welche Integration sie braucht, und die Organisation verbindet diese Integration einmal — dieselbe Verbindung, die sich jede andere Automatisierung und jeder Agent teilt. **Agents** sind die Chat- oder Aufgaben-Agents, die die Automatisierung installiert — ein Sichter, ein PR-Prüfer, ein Zusammenfasser. Einmal installiert, sind es ganz normale Agents: erwähnbar im Chat, zuweisbar auf einem Projekt-Board, editierbar im Agent-Editor. **Ein Workflow** ist die eine gebündelte Trigger-und-Schritte-Definition der Automatisierung — das, was tatsächlich nach einem Zeitplan, über einen Webhook oder per Klick läuft. Nicht jede Automatisierung liefert einen mit: Die E-Mail-Automatisierungen auf [Mitgelieferte Automatisierungen](/de/platform/automations/builtin) haben keinen, weil Mail lesen und beantworten eine Seite ist, kein geplanter Lauf. **Mitgelieferte Ansichten** sind Seiten, die die Automatisierung in die geteilte Ansichts-Registry der Plattform einträgt, etwa den Posteingang — die Plattform rendert die Seite selbst, die Automatisierung benennt nur, welche und worauf sie begrenzt ist. **Konfiguration** ist keine separate Einstellungsdatei. Eine Automatisierung, die einen Betriebswert braucht, liest ihn aus der Anmeldung einer Integration oder aus einer Trigger- oder Node-Variable des Workflows; der Tab **Konfiguration** der Automatisierung ist eine schreibgeschützte Zusammenfassung der obigen Bestandteile, kein Ort, um neue Einstellungen anzulegen. ## Der Workflow darin Eine eigenständige Workflow-Oberfläche gibt es in Tale nicht — ein Workflow lebt und läuft in seiner Automatisierung, und ihr Tab **Editor** ist der Ort, an dem du ihm begegnest. Die Definition ist ein Graph aus typisierten Schritten: **LLM**-Schritte rufen einen Agent oder ein Modell auf, **Aktion**-Schritte erledigen konkrete Arbeit wie den Aufruf einer Integration oder das Anlegen und Aktualisieren von Aufgaben auf dem Projekt-Board, **Bedingung**-Schritte verzweigen den Graphen an einem Ja oder Nein, **Schleife**-Schritte wiederholen über eine Menge, und **Sandbox**-Schritte führen Code aus. Jedes Speichern legt eine Version an, die du über **Verlauf** wiederherstellen kannst. [Der Workflow-Editor](/de/platform/automations/editor) ist das Betriebshandbuch zu dieser Oberfläche. **Trigger** entscheiden, wann der Workflow läuft. Drei Arten hängen am Tab **Trigger**: **Zeitpläne** (Cron), **Webhooks** (ein externer POST) und **Ereignisse** (etwas passiert innerhalb von Tale, etwa `task.created`) — und einen Lauf kannst du immer von Hand starten, über das Panel **Workflow testen** im Editor. Die [Trigger-Referenz](/de/platform/automations/triggers) behandelt jede Art. **Ausführungen** sind die Laufhistorie. Jeder Lauf schreibt einen Datensatz — Status, Zeiten, die empfangene Eingabe und ein Journal pro Schritt mit dem, was jeder Schritt konsumiert und produziert hat. Der Tab **Ausführungen** ist Audit-Spur und Debugging-Oberfläche in einem; [Ausführungsprotokolle](/de/platform/automations/execution-logs) liest einen Lauf von Anfang bis Ende. ## Wo Menschen mitentscheiden Automatisierungen laufen ohne dich, aber sie ändern und starten sich nur mit dir: Die vorgeschlagenen Änderungen des KI-Editors an einem Workflow landen als Genehmigungskarten, bevor sie greifen; ein Agent, der einen Workflow ausführen will, braucht zuerst deine Genehmigung; und ein Lauf, der eine Antwort braucht, pausiert als **Wartet auf Eingabe**. [Genehmigungen in Workflows](/de/platform/automations/approvals-in-workflows) behandelt alle drei. Läuft eine Schleife erneut durch dasselbe Review-Gate — eine Aufgabe, die für eine weitere Runde zurückgeht —, öffnet sie jede Runde eine frische Anfrage, statt die bereits entschiedene Karte wiederzuverwenden. ## Bundles und versteckte Automatisierungen Ein Bundle fasst mehrere Automatisierungen zusammen, die nur gemeinsam installiert einen Sinn ergeben. [GitHub-Issues lösen](/de/platform/automations/builtin) installiert vier Automatisierungen — einen Sichter, einen Abgleicher, einen PR-Ersteller und einen PR-Prüfer — über einen gebündelten Assistenten, gebunden an das Projekt, das du wählst. Die meisten Mitglieder eines Bundles sind versteckt: Sie tauchen nie als eigene Karte im Katalog auf, weil eine Installation für sich allein ohne ihre Geschwister bedeutungslos wäre. Versteckt heisst nicht weg — der [Automatisierungs-Assistent](/de/platform/automations/assistant) findet und erklärt sie trotzdem; nur das Raster des Katalogs blendet sie aus. ## Alles zusammen — zwei Kombinationen **Gmail-E-Mails synchronisieren** kombiniert die kleinstmögliche Menge: eine Integration (Gmail) und eine mitgelieferte Ansicht (Posteingang) — kein Agent, kein Workflow. Verbinde Gmail, und der Posteingang-Tab ist die ganze Automatisierung. **GitHub-Issues lösen** kombiniert jeden Bestandteil auf einmal: eine Integration (GitHub), vier Agents verteilt über seine vier versteckten Mitglieder, vier Workflows und keine mitgelieferte Ansicht — es arbeitet stattdessen über das bestehende Board und Backlog des Projekts statt über eine eigene Seite. Die Installation des Bundles verdrahtet alle vier in einem gebündelten Assistenten, gebunden an das Projekt, das du wählst. ## Wann du danach greifst | Nutz … wenn | Automatisierung | Agent | Agent-Webhook | | ---------------------------------------------------------------------------- | --------------- | ----- | ------------- | | Du willst ein fertig integriertes Feature in einem Schritt installieren | ✓ | | | | Die Arbeit hat mehrere Schritte, Verzweigungen, Zeitpläne oder Genehmigungen | ✓ | | | | Dieselbe Frage kehrt im Chat einfach wieder, kein externes System beteiligt | | ✓ | | | Eine Agent-Antwort pro eingehendem POST reicht | | | ✓ | Prüf den Katalog, bevor du irgendetwas baust — die Automatisierung, die du brauchst, wird vielleicht schon mitgeliefert. Wenn nichts Fertiges passt, baust du trotzdem eine Automatisierung: Beschreib den Workflow dem [KI-Editor](/de/platform/automations/editor) oder lade ein Paket hoch, statt lose Teile zusammenzusetzen. Ein [Agent-Webhook](/de/platform/agents/webhook-triggers) ist die eine Naht ausserhalb dieses Modells — greif dazu, wenn eine einzelne Agent-Antwort pro eingehender Nachricht alles ist, was die Aufgabe braucht. ## Bau eine Eine Automatisierung ist das ganze Bündel, das ein echtes Feature braucht — die Integration, die es aufruft, die Agents, die die Arbeit erledigen, der Workflow, der sie ausführt, die Ansicht, die es rendert —, zusammengeschaltet und in einem Schritt installiert, mit der Laufzeit des Workflows (Trigger, Ausführungen, Genehmigungen) auf den eigenen Tabs der Automatisierung. Die natürliche nächste Lektüre ist [Automatisierungen durchsuchen und installieren](/de/platform/automations/catalog) — sie geht den Katalog, das Seitenpanel und den Installations-Assistenten von Anfang bis Ende durch; [Der Workflow-Editor](/de/platform/automations/editor) übernimmt danach für die Oberfläche, auf der der Antrieb der Automatisierung gebaut und justiert wird. # Ausführungsprotokolle Source: https://tale.dev/docs/de/platform/automations/execution-logs Ausführungsprotokolle sind die Laufhistorie eines einzelnen Workflows. Jedes Mal, wenn ein Trigger feuert, öffnet Tale einen Ausführungsdatensatz und schreibt hinein, während der Lauf voranschreitet — Status, Zeiten, die empfangene Eingabe und was jeder Schritt konsumiert und produziert hat. Der Tab **Ausführungen** ist die Debugging-Oberfläche, auf die jede andere Automatisierungs-Seite zeigt, wenn etwas schiefging. <Frame caption="Der Ausführungen-Tab — eine Zeile pro Lauf; das eine rote Abzeichen zwischen den grünen ist der Startpunkt jeder Debugging-Sitzung."> ![Der Ausführungen-Tab einer Automatisierung listet zwölf Läufe — elf mit grünem Abzeichen Abgeschlossen und einer mit rotem Abzeichen Fehlgeschlagen —, jeder mit Ausführungs-ID, Startzeitstempel, Dauer und event als Trigger-Quelle.](/images/platform/automation-executions.webp) </Frame> ## Die Listenansicht Eine Zeile pro Lauf, neueste zuerst. Die Werkzeugleiste trägt **Nach Ausführungs-ID suchen**, einen **Filter** und eine Datumsbereichsauswahl. | Spalte | Beschreibung | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Ausführungs-ID | Stabile Kennung des Laufs — das Kopiersymbol legt sie in die Zwischenablage. | | Status | **Ausstehend**, **Läuft**, **Abgeschlossen** oder **Fehlgeschlagen** — dazu **Wartet auf Eingabe**, wenn ein Lauf auf einen Menschen wartet, und **Pausiert (Debug)** während eines Schritt-für-Schritt-Debug-Laufs. | | Gestartet am | Startzeit nach Wanduhr, auf die Millisekunde genau. | | Dauer | Start bis Abschluss; leer, solange der Lauf noch läuft. | | Ausgelöst von | Welcher Weg den Lauf gestartet hat — ein Zeitplan, ein Webhook, ein Ereignis oder ein Test aus dem Editor. | ## Der ausgeklappte Lauf Klappe eine Zeile aus, und der Datensatz erscheint als JSON: die Metadaten der Ausführung (Status, Zeiten, Trigger-Quelle und der Fehler, falls vorhanden), die vom Trigger mitgeführten Metadaten, die Eingabevariablen und das **Journal** — ein Eintrag pro ausgeführtem Schritt mit seinen Eingaben, Ausgaben und seinem Status. Ein fehlgeschlagener Schritt trägt den Fehlertext, der ihn beendet hat. Lies das Journal von oben nach unten, und der Lauf erzählt sich selbst nach; der Eintrag, dessen Status kippt, ist der Schritt, der sich danebenbenommen hat. ## Wiederholungen und Neustarts Vorübergehende Fehler wiederholen sich von selbst. Der Tab **Konfiguration** des Workflows setzt den Standard — **Max. Wiederholungen** und **Backoff (ms)** — und jeder Schritt kann ihn in seiner eigenen Konfiguration überschreiben. <Frame caption="Der Konfiguration-Tab — das Wiederholungsbudget und der Backoff, die jeder Schritt erbt, sofern er sie nicht überschreibt."> ![Der Konfiguration-Tab einer Automatisierung mit Feldern für Name und Beschreibung, einem Timeout von 600000 Millisekunden, maximal 3 Wiederholungen, einem Backoff von 1000 Millisekunden und einem JSON-Editor für Variablen.](/images/platform/automation-configuration.webp) </Frame> Ein Lauf, der über sein Wiederholungsbudget hinaus fehlschlägt, bleibt für die Audit-Spur **Fehlgeschlagen**; für einen neuen Versuch öffne **Workflow testen** im Editor, füge die aus dem Variablenblock des fehlgeschlagenen Laufs kopierte Eingabe ein und klicke auf **Ausführen**. Der Neustart ist eine frische Ausführung mit eigener ID. ## Eine Debugging-Sitzung, durchgespielt Ein täglicher Bericht kam nicht an. Öffne den Workflow, wechsle zu **Ausführungen** und filtere auf die heutigen Fehlschläge — der fehlgeschlagene Lauf liegt obenauf. Klappe ihn aus: Das Journal zeigt, dass der zusammenfassende Schritt an einem Timeout scheiterte, und seine Eingaben tragen den Prompt, den er erhielt. Behebe die Ursache, starte aus dem Testpanel mit derselben Eingabe neu und sieh der neuen Ausführung beim Abschließen zu, bevor du dem morgigen Zeitplan traust. ## Wo das hingehört Ausführungsprotokolle sind die Quittung, die jeder Workflow hinterlässt. Kombiniere sie mit [Triggern](/de/platform/automations/triggers) für den Startschuss, der jeden Datensatz geöffnet hat, und mit [Audit-Logs](/de/platform/admin/governance/audit-logs) für die organisationsweite Spur, wer was geändert hat. # Automatisierungs-Assistent Source: https://tale.dev/docs/de/platform/automations/assistant Der **Automatisierungs-Assistent** ist der Chat-Agent, der an die Automatisierung angeheftet ist, die du gerade geöffnet hast — klick auf **Assistent** auf der Seite einer Automatisierung, und er antwortet mit deren Agents, Workflow, Skills, Integrationen und Konfiguration bereits im Kontext. Admins und Entwickler nutzen ihn, um eine unbekannte Automatisierung zu verstehen, eine bestehende zu erweitern statt sie zu duplizieren, oder Hilfe beim Verfassen der Bestandteile zu bekommen, die die Automatisierungsseite nicht direkt editiert. Es ist derselbe Assistenten-Agent, den der [Workflow-Editor](/de/platform/automations/editor) einbettet, sodass sich eine dort begonnene Konversation auch von der anderen Oberfläche aus vertraut liest. ## Was er direkt editiert Workflows sind der eine Bestandteil, auf den der Assistent vollen Werkzeugzugriff hat: Er liest die aktuelle Definition, editiert Schritte, speichert eine neue Version und führt sie aus — genau wie wenn du selbst durch den Editor geklickt hättest. Bei Agents ist er einen Schritt zurück: Er liest die Liste und kann einen installieren, aktivieren oder deaktivieren, aber Instructions, Modell und der Rest der Konfiguration eines Agents bleiben deine eigene Aufgabe im Agent-Editor; der Assistent entwirft das genaue JSON, und du fügst es dort ein. ## Was er stattdessen entwirft Für Skills, Integrationen, mitgelieferte Ansichten und die Konfiguration einer Automatisierung gibt es überhaupt kein Editier-Werkzeug: Der Assistent schreibt die Definition im richtigen Format für Skills beziehungsweise Integrationen und sagt dir genau, wo du sie anwendest — Einstellungen > Integrationen für eine Anmeldung, die eigene Seite der Automatisierung für eine Ansicht oder ihre Konfiguration. Installation und Einrichtung laufen genauso: Er geht die Einrichtungs-Checkliste mit dir durch — verbinden, was nötig ist, Konfiguration ausfüllen, Agents und Workflow aktivieren —, statt selbst zu verbinden. ## Finden, was schon existiert Bevor er irgendetwas baut, sucht der Assistent nach einer Automatisierung oder einem Bundle, das er erweitern statt duplizieren kann — dieselbe Regel „Erst wiederverwenden, dann bauen", die auch beim Verfassen neuer Skills oder Integrationen gilt. Seine Suche reicht bis zu Automatisierungen, die der Katalog selbst versteckt: Die versteckten Mitglieder eines Bundles (siehe [Automatisierungskonzepte](/de/platform/automations/concepts)) bleiben für den Assistenten sichtbar, sodass er dich zum Beispiel auf den PR-Creator-Agent verweisen kann, der in GitHub-Issues lösen vergraben ist, statt einen neuen vorzuschlagen. ## Wo das hineinpasst Der Automatisierungs-Assistent ist der schnellste Weg in eine Automatisierung, die du nicht selbst gebaut hast — frag ihn, was etwas tut, bevor du von Hand daran rührst. [Automatisierungskonzepte](/de/platform/automations/concepts) ist das Vokabular, das er voraussetzt; [Automatisierungen durchsuchen und installieren](/de/platform/automations/catalog) ist der Ort, an dem du umsetzt, was er dir sagt, falls die Automatisierung noch nicht installiert ist. # Workflow-Trigger Source: https://tale.dev/docs/de/platform/automations/triggers Ein Trigger ist das, was einen Workflow startet, ohne dass ein Mensch etwas anklickt. Der Tab **Trigger** eines Workflows trägt drei Abschnitte — **Zeitpläne**, **Webhooks** und **Ereignisse** — und ein Workflow kann mehrere Trigger in beliebiger Mischung halten; alle füttern denselben ersten Schritt. Ein Workflow ohne Trigger läuft weiterhin von Hand über das Panel **Workflow testen** im Editor — nützlich beim Bauen, nie für die Produktion. <Frame caption="Der Trigger-Tab mit ausgeklapptem Ereignisse-Abschnitt — ein Ereignis-Trigger, sein Aktiv-Schalter und der Zeitpunkt der letzten Auslösung."> ![Der Trigger-Tab einer Automatisierung mit eingeklappten Abschnitten für Zeitpläne und Webhooks und einem ausgeklappten Ereignisse-Abschnitt mit einer task.created-Trigger-Zeile.](/images/platform/automation-triggers.webp) </Frame> ## Zeitpläne Klicke auf **Zeitplan hinzufügen**, um den Workflow nach der Uhr laufen zu lassen. Das Formular nimmt einen Standard-Cron-Ausdruck mit fünf Feldern, mit Voreinstellungen von **Alle 5 Minuten** bis **Monatlich** — oder beschreib das Timing in Alltagssprache und klicke auf **Generieren**, damit die KI den Cron-Ausdruck für dich schreibt. **Zeitzone** legt fest, in welcher Zone der Cron feuert, standardmäßig deine eigene Browser-Zone; beim Bearbeiten eines bestehenden Zeitplans bleibt dessen bisherige Zone erhalten. **Workflow-Variablen** sind die Eingabe, die jeder geplante Lauf erhält — und wenn der Start-Schritt des Workflows ein Eingabeschema deklariert, zeigt der Dialog dafür ein echtes Formular statt rohem JSON: Ein Feld `projectId` wird zu einem Auswahlfeld **Projekt**, das standardmäßig auf das eigene gebundene Projekt dieses Zeitplans zeigt, `owner` und `repo` fassen sich zu einem einzigen Feld **GitHub-Repository** zusammen, das `owner/repo` oder eine vollständige GitHub-URL annimmt, und jedes andere deklarierte Feld bekommt sein eigenes beschriftetes Eingabefeld mit der Beschreibung aus dem Schema als Hilfetext. Ein leer gelassenes Pflichtfeld zeigt seinen eigenen Fehler und blockiert **Speichern** — dieselbe Regel, die das Panel **Workflow testen** im Editor schon durchsetzt, sodass sich ein Zeitplan nicht in einem Zustand speichern lässt, den sein eigener Workflow zur Laufzeit ablehnen würde. Klicke auf **Als JSON bearbeiten**, um für ein Schema, das sich nicht als Formular darstellen lässt, auf den rohen Editor auszuweichen. Diese Variablen gelten pro Zeitplan, nicht die Standardwerte des Workflows im Tab **Konfiguration** der Automatisierung — zwei verschiedene Zeitpläne desselben Workflows können je ihr eigenes Repository oder Projekt senden, und nur was hier gesetzt ist, erreicht den Lauf. Die Zeile zeigt das gebundene **Projekt** des Zeitplans (oder **Kein Projekt**), seinen letzten Zeitpunkt unter **Zuletzt ausgelöst** und wer ihn erstellt hat. Ein Zeitplan, dem noch eine Pflichtvariable seines Workflows fehlt, trägt ein gelbes Badge **Konfiguration nötig** — fahr mit der Maus darüber für die genauen Feldnamen —, selbst wenn er aktiv ist, weil ein Lauf zur Feuerzeit mit einem leeren Pflichtwert scheitert; ein an ein Projekt gebundener Zeitplan erfüllt eine Pflichtvariable `projectId` bereits, ohne sie in den Variablen zu wiederholen. Dieselbe Lücke taucht auch im eigenen Banner **Einrichtung abschließen** der Automatisierung und im Schritt Fertig des [Installations-Assistenten](/de/platform/automations/catalog) auf — beide verlinken zurück hierher. ## Webhooks Klicke auf **Webhook hinzufügen**, und Tale prägt eine eindeutige URL; jedes System, das JSON dorthin POSTet, startet den Lauf, mit dem Body der Anfrage als Eingabe des Laufs. <Warning> Sichere die Webhook-URL, wenn sie angezeigt wird — das Token in der URL wirkt als Zugangsnachweis. Wer die URL hält, kann den Workflow starten; behandle sie also wie ein Geheimnis und lösche den Webhook, um sie zu widerrufen. </Warning> ## Ereignisse Klicke auf **Ereignis-Trigger hinzufügen** und wähle einen Ereignistyp aus dem Dropdown — Dinge, die innerhalb von Tale passieren, etwa `task.created`, `conversation.message_received`, `customer.updated` oder `workflow.completed`. Optionale Filter grenzen ein, wann der Trigger feuert, und der Payload des Ereignisses wird zur Eingabe des Laufs. Greif zum Ereignis-Trigger, wenn der Job des Workflows darin besteht, auf etwas zu reagieren, das Tale selbst gerade getan hat. <Note> Ein Workflow, der zu einer [Automatisierung](/de/platform/automations/concepts) gehört, läuft nur innerhalb seiner Automatisierung — Ereignisse kann er selbst nicht abonnieren. </Note> ## Den richtigen Trigger wählen | Nimm … wenn | Zeitplan | Webhook | Ereignis | | ------------------------------------------- | -------- | ------- | -------- | | Die Arbeit kehrt nach der Uhr wieder | ✓ | | | | Ein externes System signalisiert die Arbeit | | ✓ | | | Etwas, das Tale getan hat, ist der Anlass | | | ✓ | Ein Workflow kann mehr als einen tragen — ein täglicher Zeitplan plus ein Webhook für spontane externe Anstöße ist ein übliches Paar. ## Pausieren und entfernen Jede Trigger-Zeile hat einen **Aktiv**-Schalter. Ihn abzuschalten stoppt das Feuern, ohne die Zeile oder die Laufhistorie zu verlieren; ihn wieder einzuschalten nimmt den Betrieb sofort wieder auf. Die Zeile zu löschen ist endgültig — bei Webhooks stirbt damit auch die URL, jedes System, das noch dorthin POSTet, läuft also ins Leere. ## Wo das hingehört Trigger sind die Startschicht; die Schritte danach sind die eigentliche Arbeit. Geh zu [Automatisierungskonzepte](/de/platform/automations/concepts) für das Modell, in das ein Trigger einspeist, und zu [Ausführungsprotokolle](/de/platform/automations/execution-logs), um zu sehen, was jeder ausgelöste Lauf aufgezeichnet hat — einschließlich der Frage, welcher Trigger ihn gestartet hat. # Automatisierungen durchsuchen und installieren Source: https://tale.dev/docs/de/platform/automations/catalog Der Automatisierungen-Katalog (**Automatisierungen** in der Seitenleiste) ist der Ort, an dem Inhaber, Admins und Entwickler jede Automatisierung durchsuchen, die der Organisation zur Verfügung steht, und entscheiden, welche installiert sind. Diese Seite deckt den Katalog selbst ab — das Seitenpanel, das eine Karte öffnet, den Installations-Assistenten und die Aktionen Neu installieren, Deinstallieren und Aktualisieren, die danach folgen. Was jede mitgelieferte Automatisierung tatsächlich tut, steht auf [Mitgelieferte Automatisierungen](/de/platform/automations/builtin); das mentale Modell für die Bestandteile, die eine Automatisierung bündelt, steht auf [Automatisierungskonzepte](/de/platform/automations/concepts). <Frame caption="Der Automatisierungen-Katalog — jede Karte ist eine installierbare Automatisierung; das Bundle installiert alle seine Mitglieder über einen Assistenten."> ![Der Automatisierungen-Katalog auf dem Tab Alle Automatisierungen, mit Karten für die drei E-Mail-Automatisierungen und das Bundle GitHub-Issues lösen, jede mit Icon und Beschreibung.](/images/platform/automations-catalog.webp) </Frame> ## Installiert und Alle Automatisierungen Der Katalog öffnet sich auf **Installiert** — die Standardauswahl der Tab-Leiste, und der einzige Tab, auf dem sich ein Bundle in seine eigenen Mitglieder-Karten auflöst, statt einmal als Bundle zu erscheinen. Jedes Mitglied trägt auf seinem Icon eine kleine Markierung mit dem Namen seines Bundles — etwa **Teil von GitHub-Issues lösen** —, damit die Zugehörigkeit sichtbar bleibt, und behält sein eigenes **Neu installieren**/**Deinstallieren** im **⋯**-Menü: Ein Bundle hat schließlich keine eigene Installation, die sich als Einheit verwalten ließe (warum, steht auf [Automatisierungskonzepte](/de/platform/automations/concepts)). Wechsle zu **Alle Automatisierungen**, um stattdessen den vollständigen Katalog zu durchsuchen — mitgeliefert und hochgeladen, installiert oder nicht: Hier ist das Bundle selbst die Karte, über einen Assistenten installiert, und seine versteckten Mitglieder tauchen nie für sich allein auf. **Installiert** verwaltet, was läuft; **Alle Automatisierungen** findet Neues. ## Eine Automatisierung installieren Klick auf eine Karte, und ihr Seitenpanel öffnet sich — dasselbe Klick-zur-Vorschau-Muster, das [Einstellungen > Integrationen](/de/platform/integrations/overview) für seinen eigenen Katalog nutzt. Das Panel listet, was die Installation hinzufügt: seine Seiten, Workflows, Agents, Skills und die Integrationen, die es braucht, plus das Projekt, das es anvisiert, wenn es projektgebunden ist. Klick auf **Installieren**, und der Assistent öffnet sich. Der Assistent geht nur die Schritte durch, die diese Automatisierung wirklich braucht: einen Schritt **Projekt**, wenn sie projektgebunden ist und du sie nicht schon von innerhalb eines Projekts geöffnet hast; einen Schritt **Änderungen prüfen**, wenn die Installation bereits vorhandene Dateien überschreiben würde; einen Schritt **Installieren**, der jede benötigte, noch nicht verbundene Integration verbindet; einen Schritt **Agent-Modus** für jeden Agent, der auf deinen eigenen Zugangsdaten statt denen der Plattform laufen kann; und einen Schritt **Fertig**. Das Projekt, das du im Schritt **Projekt** wählst, übernimmt eine doppelte Aufgabe: Es ist auch die Quelle, aus der jeder von der Automatisierung installierte Zeitplan seine Variable `projectId` erhält, sodass ein Workflow, der `{{input.projectId}}` liest, gegen das richtige Projekt läuft, ohne dass du sie im [Trigger-Tab](/de/platform/automations/triggers) erneut eintippen musst. **Fertig** behauptet erst dann Bereitschaft, wenn die Automatisierung es auch ist. Ist jede erforderliche Integration verbunden, steht genau das da; ist dagegen eine erforderliche Zeitplan-Variable noch leer — wonach kein Assistent-Schritt fragt, weil es vom Eingabeschema des Workflows abhängt —, nennt Fertig sie stattdessen und bietet einen Button **Trigger öffnen**, der direkt zum betroffenen Zeitplan springt (bei einem Bundle macht der Schritt Fertig dasselbe pro Mitglied und nennt, welche noch eine Variable brauchen). Jeder Einrichtungsschritt lässt sich trotzdem später abschließen: eine übersprungene Verbindung über die eigene Checkliste **Einrichtung abschließen** der Automatisierung, eine Zeitplan-Variable über ihren [Trigger-Tab](/de/platform/automations/triggers). ## Die Prüfung vor der Installation Eine Automatisierung neu zu installieren oder erneut hochzuladen, wenn sie bereits einige ihrer Dateien geändert hat, löst vor jeder Änderung einen Schritt **Änderungen prüfen** aus. Für eine einzelne Automatisierung listet der Schritt jede Datei, die die Installation überschreiben würde, und bittet dich, das Ersetzen aller durch die Versionen der Automatisierung in einem Schritt zu bestätigen — ein Auswählen einzelner Dateien gibt es nicht. Die Installation eines **Bundles** prüft dagegen pro Mitglied-Automatisierung: Jedes Mitglied bekommt seinen eigenen einklappbaren Abschnitt und seine eigene Bestätigung, sodass du genau siehst, welche der mehreren Automatisierungen des Bundles Dateien berühren, die du geändert hast. So oder so: Die eigenen Schritte eines Workflows sind von dieser Prüfung ausgenommen — mehr dazu im nächsten Abschnitt. ## Neu installieren, deinstallieren und aktualisieren Jede installierte Karte trägt ein **⋯**-Menü mit **Neu installieren** und **Deinstallieren**; das Menü einer noch nicht installierten Karte bietet stattdessen **Installieren**, plus **Löschen** für einen privaten Upload, den du noch nicht installiert hast. **Neu installieren** durchläuft dieselbe Vorprüfung wie eine frische Installation und behält deine Umgebungsvariablen und Secrets. **Deinstallieren** entfernt die Automatisierung und alles, was sie installiert hat — ihre Agents, Workflows, Seiten sowie deren Umgebungsvariablen und Secrets —, während jede Integration, die sie genutzt hat, für alles andere verbunden bleibt, das sie braucht. Ein Neuinstallieren rührt den Workflow der Automatisierung nie an: Workflow-Schritte sind von der Aktualisierung ausgenommen, sodass alles, was du im Editor bearbeitet hast, jedes Neuinstallieren und jede Katalog-Aktualisierung übersteht. Um die neueste mitgelieferte Version eines Workflows zu holen, deinstallierst du die Automatisierung und installierst sie erneut — Tale wiederholt diesen Hinweis sowohl auf der Neuinstallations-Bestätigung als auch auf dem eigenen Tab **Konfiguration** der Automatisierung. **Mitgelieferte Automatisierungen aktualisieren**, im selben Menü **Automatisierung hinzufügen** wie **Paket hochladen**, ist eine andere Aktion als die beiden vorigen: Sie gleicht jede mitgelieferte Automatisierung der Organisation in einem Durchgang gegen den mitgelieferten Katalog ab — auch die, die du bearbeitet hast —, statt eine Karte nach der anderen. Sie trägt dieselbe Workflow-Ausnahme und behält Secrets; die vorherige Version von allem, was sie ändert, landet im Verlauf der jeweiligen Automatisierung. ## Eine private Automatisierung hochladen **Paket hochladen** im selben Menü fügt eine Automatisierung hinzu, die der Katalog nicht mitliefert — leg ein `.zip` ab, oder wähl einen Ordner mit einer `automation.json` in seinem Stammverzeichnis; der Ordner- oder Dateiname wird zum Slug der Automatisierung. Das Hochladen fügt sie nur dem privaten Katalog der Organisation hinzu; installiere sie danach wie jede andere Karte. Erneutes Hochladen über einen bereits vorhandenen Slug bittet dich, das Ersetzen zu bestätigen, bevor es das vorhandene Paket überschreibt. ## Wo das hineinpasst Der Katalog ist die Eingangstür zu jeder Automatisierung, die die Organisation ausführen kann: Das Seitenpanel zeigt vorab, was eine Installation hinzufügt, der Assistent verbindet, was sie braucht, und Neuinstallieren, Deinstallieren und Aktualisieren halten sie aktuell, ohne einen Workflow anzurühren, an dem du gerade arbeitest. [Mitgelieferte Automatisierungen](/de/platform/automations/builtin) ist die nächste Lektüre dafür, was jede mitgelieferte Automatisierung und das Bundle GitHub-Issues lösen tatsächlich tun; [Automatisierungskonzepte](/de/platform/automations/concepts) ist das mentale Modell, falls du es noch nicht gelesen hast. # Genehmigungen in Workflows Source: https://tale.dev/docs/de/platform/automations/approvals-in-workflows Workflows laufen ohne dich, aber sie ändern sich und starten nur mit dir. Drei menschliche Tore umgeben jeden Workflow: Die Änderungen des KI-Editors an einer Definition greifen erst nach deiner Genehmigung, ein Agent, der einen Workflow starten will, braucht zuerst dein Einverständnis, und ein Lauf, der auf eine Frage stößt, pausiert, bis jemand antwortet. Diese Seite behandelt die drei Tore; die organisationsweite Geschichte, was eine Genehmigungskarte ist, steht auf [Genehmigungskonzepte](/de/platform/approvals/concepts). <Frame caption="Der KI-Editor neben der Leinwand — seine Änderungen kommen als Genehmigungskarten an, nie als stille Eingriffe in die Definition."> ![Der Workflow-Editor mit einem Schritt-Graphen auf der Leinwand und rechts dem geöffneten Panel des KI-Editors, in dem vorgeschlagene Workflow-Änderungen zur Genehmigung erscheinen.](/images/platform/automation-editor-canvas.webp) </Frame> ## Änderungen an einer Definition genehmigen Bitte den **KI-Editor**, einen Workflow zu bauen oder umzubauen, und sein Vorschlag landet als Karte im Panel — eine Karte **Workflow erstellen** mit der Schrittzahl für eine neue Definition oder eine Aktualisierungskarte mit einem Badge nach Umfang: **Schritt aktualisieren** für einen Einzelschritt-Patch, **{count} Schritte aktualisieren** für mehrere, **Workflow aktualisieren** für ein vollständiges Speichern. Genehmigst du, wendet Tale die Änderung an und versioniert sie wie jedes manuelle Speichern; **Abbrechen** verwirft sie. Nichts berührt die Definition, solange die Karte aussteht. ## Einen Lauf genehmigen Ein Agent im Chat mit den Workflow-Tools kann darum bitten, einen Workflow zu starten. Die Anfrage kommt als Karte an, die den Workflow benennt — klappe **Parameter anzeigen** aus, um die genaue Eingabe zu prüfen, mit der er laufen wird — und hält, bis du auf **Workflow ausführen** oder **Abbrechen** klickst. Nach der Genehmigung verfolgt dieselbe Karte den laufenden Lauf: den aktuellen Schritt, die verstrichene Zeit und das Ergebnis, mit **Stopp** zum Abbrechen mitten im Flug und **Ausführungsdetails anzeigen** als Sprung ins Journal des Laufs. <Note> Der Chat-Composer ist blockiert, solange eine Anfrage aussteht — **Beantworte die ausstehende Anfrage oben, um fortzufahren**. Entscheide die Karte, bevor du die nächste Nachricht schickst. </Note> ## Einen pausierten Lauf beantworten Ein Lauf, der eine menschliche Antwort braucht, pausiert mit dem Status **Wartet auf Eingabe** in der [Ausführungsliste](/de/platform/automations/execution-logs). Die Frage kommt als Formularkarte an — fülle sie aus und klicke auf **Antwort absenden**, oder klicke auf **Anders antworten**, um in freiem Text zu widersprechen. Der Lauf setzt mit deiner Antwort als Eingabe des Schritts fort, und das Journal hält fest, wer geantwortet hat und was. ## Was jede Entscheidung hinterlässt Jedes Tor löst sich in dieselben Zustände auf — **Ausstehend**, **Wird ausgeführt**, **Abgeschlossen** oder **Abgelehnt** — sichtbar auf der Karte selbst, und die Entscheidung landet im [Audit-Log](/de/platform/admin/governance/audit-logs) mit Akteur und Zeitstempel. Eine entschiedene Karte lässt sich nicht wieder öffnen; um einen abgelehnten Lauf erneut zu versuchen, frag noch einmal und entscheide die frische Karte. ## Wo das hingehört Diese Tore sind die Workflow-Seite eines produktweiten Musters: Ein Agent schlägt vor, ein Mensch entscheidet. [Genehmigungskonzepte](/de/platform/approvals/concepts) benennt jeden Kartentyp jenseits von Workflows — Dokument-Schreibzugriffe, Wissens-Schreibzugriffe, Integrationsaufrufe — und [Genehmigungen konfigurieren](/de/platform/approvals/configure) zeigt, wo die Anforderungen deklariert sind. # Der Workflow-Editor Source: https://tale.dev/docs/de/platform/automations/editor Diese Seite ist das Betriebshandbuch zum Workflow in einer Automatisierung — der Oberfläche hinter dem Tab **Editor**. Das mentale Modell — was eine Automatisierung bündelt und was eine Definition, ein Trigger und eine Ausführung sind — lebt auf [Automatisierungskonzepte](/de/platform/automations/concepts). Diese Seite ist die praktische Hälfte: wo der Workflow lebt, wie du ihn aus der UI startest, wie du ihn ohne Löschen pausierst, wie du editierst und wie die versionierte Historie funktioniert. Redakteure und Entwickler lesen das, wenn sie täglich mit einem Workflow arbeiten. ## Wo Workflows leben Workflows haben keinen eigenen Tab in der Seitenleiste. Ein Workflow gehört zu der Automatisierung, die er antreibt — öffne die Automatisierung, und ihr Tab **Editor** ist der Workflow; von dort aus verwaltest du alles Weitere. Ein direkter Link auf einen Workflow funktioniert weiter, wenn ihn jemand teilt; Lesezeichen und die Links auf Genehmigungs-Karten und Ausführungs-Ansichten landen auf dem Workflow selbst. Jede Oberfläche, die diese Seite behandelt (der Editor, der Ausführungen-Tab, die Versionshistorie), hängt an einem einzelnen Workflow, den du geöffnet hast. ## Einen Workflow starten Drei Pfade feuern einen Workflow. Der Tab **Trigger** am Workflow hängt die Produktionspfade an: **Zeitpläne** feuern per Cron, **Webhooks** nehmen einen externen POST entgegen, und **Ereignisse** abonnieren interne Signale wie `task.created`. Die [Trigger-Referenz](/de/platform/automations/triggers) deckt jeden einzelnen in Tiefe ab. **Workflow testen** in der Editor-Toolbar öffnet das Test-Panel und feuert einen einmaligen Lauf. Füge die Eingabe-JSON ein, die der Lauf erhalten soll, klick auf **Ausführen**, und der Lauf taucht im Ausführungen-Tab mit seiner ID auf. Greif zum Test-Panel, wenn du an einem Workflow iterierst und das volle Ausführungsjournal sehen willst, ohne erst einen Trigger zu verdrahten. Während der Lauf läuft, spiegelt die Canvas ihn live: Jeder Schritt trägt ein Status-Badge — ein Spinner während der Ausführung, ein Häkchen bei Erfolg, ein Warnsymbol bei Fehlern, ein Pause-Symbol beim Warten auf Eingabe — und ein Banner über der Canvas zeigt, welcher Lauf gerade angezeigt wird. Klick auf ein Badge, um Dauer, Fehler und eine Vorschau der Ausgabe des Schritts zu prüfen. Der angezeigte Lauf hängt am URL-Parameter `execution` und übersteht damit ein Neuladen; schließt du das Banner, verschwinden die Badges. Das Test-Panel spiegelt denselben Feed als Schrittliste: Jeder ausgeführte Schritt erscheint mit seinem Live-Status, wiederholte oder geschleifte Schritte tragen einen Versuchszähler, und ein fehlgeschlagener Schritt zeigt seine Fehlermeldung direkt darunter — klick auf den Namen des Schritts, um direkt zu seinen Einstellungen zu springen. Schlägt ein Lauf fehl, bevor irgendein Schritt lief — nie gestartet, Zeitlimit überschritten oder abgebrochen —, nennt das Panel stattdessen diesen Grund. Testläufe validieren die Eingabe zudem serverseitig gegen das Schema des Start-Schritts: Ein fehlendes oder falsch typisiertes Feld wird mit einer feldgenauen Meldung abgewiesen, bevor der Lauf überhaupt entsteht. Der **Debuggen**-Button im selben Panel startet den Lauf im Schritt-für-Schritt-Modus. Die Engine hält vor jedem Schritt an: Der pausierte Schritt trägt ein Debug-Badge auf der Canvas, und das Panel zeigt, welcher Schritt als Nächstes dran ist, samt den Variablen des Laufs und der Ausgabe jedes abgeschlossenen Schritts — so prüfst du, was ein Schritt gleich erhält, bevor er läuft. **Schritt** führt den pausierten Schritt aus und hält vor dem nächsten wieder an, **Fortsetzen** lässt den Rest des Workflows ohne weitere Pausen durchlaufen, **Stoppen** bricht den Lauf ab. Debug-Läufe erscheinen im Ausführungen-Tab mit dem Badge _Pausiert (Debug)_, solange sie pausiert sind, und mit `debug` als Auslöser. Der **Probelauf**-Button im selben Panel simuliert einen Lauf ohne Seiteneffekte — der Workflow validiert gegen die Eingabe, läuft den Schritte-Graph ab und meldet Fehler und Warnungen, ohne irgendeinen Agent, eine API oder einen Mail-Server zu rufen. Greif zum Probelauf, wenn der Workflow noch nicht sicher genug ist, um ihn von Anfang bis Ende laufen zu lassen. ## Pausieren und deaktivieren Einen Workflow pausieren, ohne ihn zu löschen, geht über die Trigger — jede Trigger-Zeile hat einen **Aktiv**-Schalter. Schalte jeden Trigger aus, hört der Workflow auf zu feuern; schalte sie wieder an, läuft er weiter. Der Workflow selbst bleibt bestehen und seine Historie bleibt intakt. Einen Workflow löschen ist permanent. Tale fragt vor dem Löschen nach Bestätigung; die Ausführungen und die Versionshistorie gehen mit dem Workflow weg. ## Editieren Öffne den Workflow, und der Editor zeigt den Schritte-Graph auf einer Canvas — das ist die Ansicht **Graph**, eine von zwei Arten, dieselbe Definition zu lesen. Wechsle zu **Spezifikation**, und derselbe Workflow liest sich als Beschreibung in normaler Sprache, die du direkt editieren kannst; das Generieren aus beiden Ansichten hält sie synchron, und ein Banner warnt, wenn sie auseinanderdriften. Klick auf einen Schritt im Graphen, um rechts das Panel **Schritt-Editor** zu öffnen; das Panel trägt Name, Typ und Konfiguration des Schritts sowie die Übergänge zu den nächsten Schritten bei Erfolg und Fehler. Die Canvas-Toolbar trägt die Zoom-Steuerung, **Workflow testen** und den Schalter **KI-Editor** — ein Chat, der den Workflow für dich editiert, derselbe [Automatisierungs-Assistent](/de/platform/automations/assistant), hier eingebettet. Schritte direkt auf der Canvas hinzuzufügen ist noch nicht verdrahtet; neue Schritte kommen aus dem KI-Editor oder aus der Spezifikation. Das Banner **Dieser Workflow ist aktiv — gespeicherte Änderungen gelten für neue Ausführungen.** über der Canvas meint genau das: Änderungen an einem getriggerten Workflow greifen beim nächsten Lauf. Schalte seine Trigger zuerst aus, wenn die Änderungen noch nicht fertig sind. ## Versionierung und Historie Jedes Speichern schnappschotet eine neue Version des Workflows. **Verlauf** in der Navigation des Workflows listet die Versionen, neueste zuerst, jede mit Zeitstempel und dem Mitglied, das gespeichert hat. Öffnest du eine, zeigt **Änderungen vergleichen** einen Diff gegen die aktuelle Definition; klick auf **Wiederherstellen**, um auf diesen Schnappschuss zurückzurollen. Das Wiederherstellen legt eine neue Version oben auf den Verlauf — der zurückgerollte Zustand ist der neue aktuelle, und die Version, die du ersetzt hast, steht weiter in der Liste. Die Historie ist pro Workflow, nicht pro Schritt. Wiederherstellen rollt die ganze Definition; partielle Wiederherstellungen leben im Editor (kopier die Schritt-Konfig aus dem Diff und füg sie in die aktuelle Version ein). Ein Neuinstallieren oder Aktualisieren der Automatisierung, zu der dieser Workflow gehört, rührt diese Schritte nie an — ein Workflow ist von diesem Überschreiben ausgenommen, genau damit deine Änderungen eine Katalog-Aktualisierung überstehen. Deinstallier die Automatisierung und installier sie erneut, um stattdessen ihren neuesten mitgelieferten Workflow zu übernehmen. ## Wo das eingesetzt wird Diese Seite ist das Betriebshandbuch; [Automatisierungskonzepte](/de/platform/automations/concepts) ist das mentale Modell. Die natürlichen Nachbarn sind [Trigger](/de/platform/automations/triggers) (der Startschuss), [Ausführungsprotokolle](/de/platform/automations/execution-logs) (die Detailansicht pro Lauf) und [Genehmigungen in Workflows](/de/platform/automations/approvals-in-workflows) (die menschliche Schranke zwischen Schritten). Greif zu dieser Seite, wenn du mit einem bestehenden Workflow arbeitest; greif zu den Konzepten, wenn du deinen ersten baust. # Plattform Source: https://tale.dev/docs/de/platform Plattform ist die kanonische Produktreferenz: jedes nutzersichtbare Feature in Tale, identisch für Cloud und selbst gehostet. Die Seiten hier beschreiben die UI, die jemand anklickt, das Konzept dahinter und die Trade-offs zwischen Features, die ähnlich aussehen. Der Abschnitt ist nach Bereich und innerhalb eines Bereichs nach Feature gegliedert. Die meisten Leser arbeiten ihn nicht von vorne bis hinten durch — sie landen aus einer Suche oder aus einem Tutorial-Link hier, und die Seite, auf der sie landen, sollte die Frage beantworten, die sie mitgebracht haben. ## Feature-Bereiche <CardGroup cols="2"> <Card title="Chat" icon="message-circle" href="/de/platform/chat/overview"> Der alltägliche Einstieg — Konversationen, Agents im Chat, Anhänge, Arena-Modus, Sprachmodus, der Canvas-Bereich, Teilen. </Card> <Card title="Projekte" icon="folder-open" href="/de/platform/projects/overview"> Geteilte Arbeitsbereiche, die Dateien, Anweisungen, Konversationen und projektgebundene Agents bündeln. </Card> <Card title="Agents" icon="bot" href="/de/platform/agents/concepts"> Anweisungen, Wissen, Tools, Modell — plus Fähigkeiten, Worker, Versionierung und Webhook-Trigger. </Card> <Card title="Automatisierungen" icon="layout-grid" href="/de/platform/automations/concepts"> Installierbare Bündel aus Integrationen, Agents, Skills und einem Workflow — der Katalog, der Installations-Assistent, der Editor und die Trigger hinter jeder Automatisierung und die Laufhistorie, die sie hinterlässt. </Card> <Card title="Wissen" icon="library" href="/de/platform/knowledge/overview"> Dokumente, Kunden, Produkte, Lieferanten, Websites — das Modell für strukturierte Daten, das Agents zitieren. </Card> <Card title="Genehmigungen" icon="check-check" href="/de/platform/approvals/concepts"> Inline-Karten, Workflow-Gates und der Genehmiger-Pool, der Menschen in der Schleife hält. </Card> <Card title="Prompt-Bibliothek" icon="list-plus" href="/de/platform/workspace/prompt-library"> Gespeicherte Prompts mit persönlicher, Team- und globaler Sichtbarkeit, plus Versionsverlauf. </Card> <Card title="Modelle" icon="cpu" href="/de/platform/models"> Der Modellkatalog hinter jedem Picker — Fähigkeits-Tags, Standards und die ausgelieferte Liste. </Card> <Card title="Integrationen" icon="plug" href="/de/platform/integrations/overview"> Drittanbieter-Pairings und MCP-Server. </Card> </CardGroup> ## Richte deinen ersten Tag ein Vier rollenbasierte Einträge zeigen dieselben Features von der Seite des Lesers — was ein Mitglied, ein Redakteur, ein Entwickler oder die Verwaltung am ersten Tag tatsächlich anfasst. <CardGroup cols="2"> <Card title="Mitglied" icon="user" href="/de/platform/member/overview"> Chat, Wissen, persönliche Einstellungen — die Oberfläche, die die meisten Leute in den meisten Orgs nutzen. </Card> <Card title="Redakteur" icon="pencil-ruler" href="/de/platform/editor/overview"> Die Bau-Oberfläche — Agents, Wissenspflege, Automatisierungen, Projekte. </Card> <Card title="Entwickler" icon="terminal" href="/de/platform/developer/overview"> API-Schlüssel, eigene Tools, Webhooks, MCP-Server — Tale an externen Code anbinden. </Card> <Card title="Verwaltung" icon="shield" href="/de/platform/admin/overview"> Organisationseinstellungen, Anbieter, Branding, Integrationen und der Governance-Unterzweig. </Card> </CardGroup> ## Wo das hingehört Plattform ist der Gravitationsbrunnen — Cloud und selbst gehostet verlinken beide für Feature-Dokumentation hier hinein, und jedes Tutorial zitiert Seiten von hier für die zugrundeliegenden Konzepte. Die Seite, die du dir an deinem ersten Tag setzen willst, ist [Agents → concepts](/de/platform/agents/concepts) — fast jede andere Produktseite setzt das Vier-Knöpfe-Modell voraus, das dort aufgebaut wird. # Mitglied Source: https://tale.dev/docs/de/platform/member/overview Mitglied ist die Standardrolle, die die meisten Personen in den meisten Organisationen tragen. Es ist die Endbenutzer-Oberfläche von Tale — mit Agents chatten, durch die Wissensdatenbank stöbern, in der Inbox einer installierten Automatisierung auf Kunden-E-Mails antworten, die Genehmigungen entscheiden, die andere zu dir geroutet haben, und Feedback zu Antworten hinterlassen. Mitglieder bauen keine Agents, konfigurieren keine Anbieter, installieren keine Automatisierungen. Sie nutzen das Produkt, das die Redakteure und Entwickler für sie gebaut haben. Diese Übersicht nennt, was ein Mitglied tun kann, und verweist auf die Per-Funktions-Seiten. Mitglieder landen typischerweise zuerst auf Chat; der Rest dieser Seite ist das, was du liest, wenn Chat allein nicht reicht — wenn du wissen willst, woher ein Zitat kam, was eine Genehmigungs-Karte ist oder was ein Projekt bündelt. ## Was Mitglied abdeckt Die Mitglieder-Oberfläche ist bewusst eng. Die vier Kübel sind: - **Chat** — einen Agent (oder keinen) wählen, eine Nachricht senden, die Antwort lesen. Der Composer legt die Prompt-Bibliothek, Anhänge, Voice-Modus, Arena-Modus für Seite-an-Seite-Vergleich und die Canvas-Spalte frei, wenn eine Antwort mehr produziert, als der Chat inline halten kann. - **Wissen** — Dokumente, Kunden, Produkte, Lieferanten, Websites durchstöbern, die die Organisation geladen hat. Nur-Lese für Mitglieder; das Kuratieren passiert auf der Redakteur-Seite. - **Inbox** — im Tab **Inbox** antworten, den eine installierte E-Mail-Automatisierung hinzufügt. Mitglieder antworten, wenn ein Agent eine Konversation zurückgibt; die Automatisierung selbst zu installieren ist eine Admin-Aktion. - **Genehmigungen** — die Genehmigungs-Karten lesen, die zu dir geroutet wurden. Klick auf Genehmigen, Ablehnen oder Änderungen anfordern; hinterlass einen Kommentar, wenn die Regel danach fragt. Die Org-Konfigurationseinstellungen — Anbieter, Integrationen, Agents, Governance — sind für Mitglieder ausgeblendet; was bleibt, ist zum Großteil die Arbeits-Oberfläche. Die Ausnahme ist eine kleine persönliche Einstellungs-Gruppe, die jede Rolle trägt: Konto, Personalisierung und [Umgebungsvariablen & Geheimnisse](/de/platform/member/environment), die Schlüssel und Variablen, die in die Sandboxes injiziert werden, die du fährst. ## Seiten in diesem Bereich Dieser Bereich ist kurz — die Mitglieder-Oberfläche ist die Querschnittsmenge der Seiten, für die Redakteure bauen und die alle nutzen. Die tiefere Lektüre liegt in den Per-Funktions-Bereichen. <CardGroup cols="2"> <Card title="Chat" icon="message-circle" href="/de/platform/chat/overview"> Der alltägliche Einstieg — Composer, Agents, Anhänge, Zitate. </Card> <Card title="Wissen" icon="library" href="/de/platform/knowledge/overview"> Das Nur-Lese-Fenster in das, was die Organisation geladen hat. </Card> <Card title="Mitgelieferte Automatisierungen" icon="inbox" href="/de/platform/automations/builtin"> Die E-Mail-Automatisierungen, die einen Inbox-Tab hinzufügen — und was jede einzelne tut. </Card> <Card title="Genehmigungen" icon="check-check" href="/de/platform/approvals/concepts"> Was eine Genehmigungs-Karte ist und was jeder Knopf tut. </Card> </CardGroup> ## Wo das hingehört Mitglied ist die Rolle, die konsumiert, was der Redakteur baut und der Admin steuert. Die natürliche Erstlektüre ist [Chat](/de/platform/chat/overview) — dort verbringt jedes Mitglied die meiste Zeit, und die meisten anderen Mitglieder-Oberflächen fächern sich von einem Chat aus, der mehr tun wollte. # Einstellungen Source: https://tale.dev/docs/de/platform/member/preferences Einstellungen sind die Schrauben, die dir gehören, nicht der Organisation. Dein Name ist das, was Agents und Teamkolleginnen in Chats und Genehmigungen sehen. Deine Locale und dein Theme folgen dir zwischen Geräten. Deine eigenen Anweisungen und Erinnerungen prägen, wie Agents speziell dir antworten — getrennt von allem, was Admin oder Redakteur auf Organisationsebene gesetzt hat. Diese Seite zeigt, wo jeder Hebel sitzt und was er ändert. Die Form ist bewusst zweischichtig: das Profilmenü (überall, einen Klick vom Avatar entfernt) trägt die schnellen Schalter; **Einstellungen > Konto** und **Einstellungen > Personalisierung** tragen die tieferen Kontofelder. Alles hier gehört dir — nichts davon lecken zu anderen Mitgliedern oder anderen Organisationen durch. ## Das Profilmenü Klick auf deinen Avatar oben rechts. Das Dropdown öffnet sich mit deinem Namen, deiner E-Mail und der aktuellen Build-Version. Unter dem Kopf sitzen vier Schnellschalter, die jedes Mitglied unabhängig von der Rolle sieht: der Theme-Wechsler (**Systemdesign** / **Helles Design** / **Dunkles Design**), das **Sprach**-Untermenü (English, Deutsch, Français), die Zeile **App installieren**, wenn der Browser Tale als PWA installieren kann, und **Abmelden**. Theme und Sprache greifen sofort und bleiben pro Gerät erhalten. Das Menü trägt außerdem einen Organisationswechsler, wenn du zu mehr als einer Organisation gehörst, und einen Team-Filter, wenn deine aktuelle Organisation Teams hat. Das sind keine Einstellungen — sie ändern, was Tale dir zeigt, nicht wie Tale sich verhält. Unter dem Team-Filter öffnet **Benutzereinstellungen** den Bereich **Einstellungen > Konto**, die nächste Seite hier. ## Konto — Name, E-Mail, Passwort, Zwei-Faktor Öffne **Einstellungen > Konto**. Drei Abschnitte sitzen auf der Seite: **Profil**, **Sicherheit** und **Zwei-Faktor-Authentifizierung**. Der Profil-Abschnitt zeigt zuerst deine **E-Mail**, dann deinen **Namen** — die E-Mail legt den Namen nahe, den Tale vorschlägt und den du frei bearbeiten kannst. Der Name ist inline bearbeitbar; die Änderung speichert und schlägt beim nächsten Render in jedem Chat und jeder Genehmigung durch. Die E-Mail ist schreibgeschützt — sie ist das, womit du dich angemeldet hast, und ein Wechsel läuft über den Support. Es gibt kein Avatar-Feld auf der Seite; Tale leitet einen Avatar aus den Initialen deines Namens ab. Der Sicherheits-Abschnitt hält einen einzelnen Knopf: **Passwort ändern**, wenn du dich mit E-Mail und Passwort registriert hast, **Passwort festlegen**, wenn dein Konto über SSO föderiert ist und du ein Passwort als Rückfall hinzufügen willst. Beide Abläufe erzwingen die Passwort-Richtlinie der Organisation und zeigen die Regeln live, während du tippst, und ein falsches aktuelles Passwort wird direkt am Feld markiert statt als flüchtiger Fehler. Das Ändern deines Passworts meldet dich auf allen Geräten ab — der Dialog warnt dich, bevor du bestätigst, und du meldest dich anschließend mit dem neuen Passwort wieder an. Der Zwei-Faktor-Abschnitt paart das Konto mit einer TOTP-App oder einem Hardware-Schlüssel und zeigt die Backup-Codes einmal bei der Einrichtung. ## Personalisierung — benutzerdefinierte Anweisungen, Erinnerungen, Sprachausgabe Öffne **Einstellungen > Personalisierung**. Die Seite öffnet jede Funktion mit einem An/Aus-Schalter, der dem Org-Standard folgt, bis du ihn überschreibst. <Frame caption="Einstellungen > Personalisierung — die Schalter je Funktion über dem Feld für benutzerdefinierte Anweisungen, der Erinnerungs-Liste und dem Sprachausgabe-Picker."> ![Die Personalisierungs-Einstellungsseite, mit An/Aus-Schaltern für benutzerdefinierte Anweisungen, Erinnerungen und Sprachausgabe, darunter das Textfeld für benutzerdefinierte Anweisungen und die Liste gespeicherter Erinnerungen.](/images/platform/settings-preferences.webp) </Frame> **Benutzerdefinierte Anweisungen** ist ein freies Textfeld — bis zu 4.000 Zeichen —, das jeder Agent speziell für deine Konversationen als zusätzlichen Kontext erhält. Nutz es für das, was du sonst oben in jeden Chat schreiben würdest: deine Rolle, deinen bevorzugten Antwortstil, die Projekte, an denen du arbeitest, die Einschränkungen, die der Agent achten soll. Der Org-Standard entscheidet, ob die Funktion für neue Mitglieder an ist; dein Schalter überschreibt ihn für dein eigenes Konto. **Erinnerungen** sind kurze Fakten, die der Agent zwischen Chats über dich speichert — ein Thema, nach dem du gefragt hast, eine Vorliebe, die du genannt hast, ein Kontext, den du nicht wiederholen willst. Gespeicherte Erinnerungen erscheinen in einer Liste mit einem Lösch-Knopf je Zeile; ausstehende Erinnerungen tauchen in einem eigenen Abschnitt mit **Genehmigen** und **Verwerfen** auf, damit nichts in deinem Profil landet, ohne dass du es siehst. Schalte die Funktion ab, und bestehende Erinnerungen werden nicht mehr genutzt, bis du sie wieder einschaltest. **Sprachausgabe** wählt die Stimme, die ein Agent im Voice-Modus benutzt. Die Einstellung greift nur, wenn die Organisation einen Voice-Anbieter konfiguriert hat; sonst erklärt der Abschnitt die Lücke und verweist auf den Admin. ## Abmelden Die Zeile **Abmelden** unten im Profilmenü bestätigt mit einem Dialog, bevor sie die Session löscht. Nach der Bestätigung lädt Tale die Seite zur Anmeldeseite hart neu, damit kein veralteter Zustand im Tab hängenbleibt. Das Abmelden ist pro Gerät — dich auf dem Laptop abzumelden, meldet dich nicht auf dem Handy ab, und umgekehrt. ## Wo das hingehört Einstellungen sind die Linie zwischen dir und dem Rest der Organisation. Der Org-Admin setzt Standardwerte — inklusive ob Personalisierung für neue Mitglieder an ist, was die Passwort-Richtlinie ist, welche Modelle erlaubt sind — und deine Einstellungen überschreiben die Standardwerte dort, wo Tale es zulässt. Eine persönliche Seite steht abseits dieses Sets: [Umgebungsvariablen & Geheimnisse](/de/platform/member/environment) hält Variablen und Anmeldedaten, die innerhalb einer einzelnen Organisation auf dich begrenzt sind, statt dir über Organisationen hinweg zu folgen — der Ort für den Provider-Schlüssel, den ein BYO-Agent benutzt. Die nächste Lektüre, die sich lohnt, ist [Mitglieds-Übersicht](/de/platform/member/overview) für die Karte des restlichen Mitglieder-Bereichs, oder [Als App installieren](/de/platform/member/install-as-app), wenn du willst, dass Tale in deinem Dock statt in deinen Browser-Tabs lebt. # Umgebungsvariablen & Geheimnisse Source: https://tale.dev/docs/de/platform/member/environment Umgebungsvariablen & Geheimnisse ist dein persönlicher Speicher für Variablen, die Tale in jede Agent-Sandbox einspeist, die du in dieser Organisation startest. Startet ein externer Agent seine Sandbox, setzt Tale jeden hier gespeicherten Eintrag in die Umgebung des Containers, bevor der Agent läuft — ein Befehl, den der Agent absetzt, oder der Agent selbst kann ihn dann lesen. Der Hauptzweck sind Anmeldedaten: ein [externer BYO-Agent](/de/platform/agents/external-agent) authentifiziert sich mit dem API-Schlüssel oder Token, den du hier hältst, statt über das Plattform-Gateway. Es ist eine Seite auf Mitglieds-Ebene, die jede Rolle erreicht, und die Einträge sind auf dich und die aktuelle Organisation begrenzt — sie lecken nie zu Teamkolleginnen durch und folgen dir nie in eine andere Organisation. Diese Seite zeigt die zwei Arten von Eintrag, wie Geheimnisse geschützt werden, welche Regeln Name und Wert erfüllen müssen, und wo die Werte landen. <Frame caption="Einstellungen > Umgebung — die gespeicherten Einträge, jeder mit dem Schalter Geheim, der entscheidet, ob sein Wert zurückgelesen werden kann."> ![Die Umgebungs-Einstellungsseite listet drei gespeicherte Einträge — ANALYTICS_ORG und CRM_BASE_URL mit offen sichtbaren Werten und CRM_API_TOKEN als Punkte maskiert, mit angehaktem Kästchen Geheim — über der Aktion Variable hinzufügen.](/images/platform/settings-environment.webp) </Frame> ## Variablen und Geheimnisse Öffne **Einstellungen > Umgebung**. **Variable hinzufügen** öffnet einen Dialog für einen neuen Eintrag, darunter steht die Liste dessen, was du gespeichert hast. Jeder Eintrag hat einen **Name** und einen **Wert**, dazu einen **Geheimnis**-Schalter, der entscheidet, wie der Wert gespeichert und angezeigt wird. Eine einfache Variable wird unverändert gespeichert und in der Liste in voller Länge zurückgezeigt — nimm sie für unkritische Konfiguration, die der Agent erwartet, einen Regionsnamen oder einen Endpunkt. Ein **Geheimnis** wird im Moment des Speicherns verschlüsselt und ist von da an schreibgeschützt: Die Liste zeigt `••••••••` statt des Werts, und es gibt keinen Weg, ihn zurückzulesen. Schalt den Schalter für alles Sensible ein — einen API-Schlüssel, einen OAuth-Token, ein Passwort. Der Preis dafür ist, dass du den Wert eines Geheimnisses später nicht mehr prüfen kannst: Bist du dir unsicher, ob er stimmt, lösch ihn und füg ihn neu hinzu, statt nach einem Anzeigen-Knopf zu suchen, den es nicht gibt. Jede Zeile trägt den Namen, den Wert oder seine Maske, und wann er zuletzt aktualisiert wurde. Das Papierkorb-Symbol fragt vor dem Entfernen nach Bestätigung, denn einen Eintrag zu löschen nimmt ihn beim nächsten Lauf aus jeder deiner Sandboxes. ## Namen, Werte und Grenzen Ein **Name** muss mit einem Buchstaben oder Unterstrich beginnen und darf nur Buchstaben, Ziffern und Unterstriche enthalten — die Form einer gewöhnlichen Umgebungsvariable, `MY_API_KEY` statt `my-api.key`. Namen sind auf 128 Zeichen begrenzt, Werte auf 8.192 — Platz für einen langen Token oder einen mehrzeiligen Schlüssel, aber nicht für eine Datei. Du kannst bis zu 100 Einträge halten. Tale schneidet Leerzeichen am Anfang und Ende eines Werts beim Speichern ab, denn ein versehentlicher Zeilenumbruch aus dem Kopieren ist der häufigste Grund, warum ein Token still fehlschlägt. Leerzeichen oder Zeilenumbrüche _innerhalb_ des Werts bleiben unangetastet, aber Tale warnt, wenn es welche findet: Anmeldedaten haben normalerweise keine, also bedeutet Leerraum im Inneren meist, dass ein Token beim Einfügen über mehrere Zeilen in deinem Terminal umbrochen wurde. Die Warnung blockiert das Speichern nicht — ein echt mehrzeiliges Geheimnis wie ein privater PEM-Schlüssel behält seine Zeilenumbrüche —, also lies sie und entscheide selbst. ## Wie die Werte in die Sandbox kommen Ein Geheimnis reist nie im Klartext, außer in deine eigene Sandbox. In Ruhe liegt es im Backend von Tale verschlüsselt, unter einem Schlüssel, den die Plattform hält, und die Listen-Abfrage liefert nur die Maske zurück, nie den Klartext. Beginnt ein Turn, entschlüsselt die Plattform deine Geheimnisse und setzt sie, neben deinen einfachen Variablen, in die Umgebung deiner Sandbox für diesen Lauf. Wird ein Geheimnis für einen Turn eingespeist, hält das Audit-Log diesen Zugriff fest. Dieser letzte Schritt ist die Grenze, die es zu verstehen lohnt: Die Werte landen in deinem Sandbox-Container, also ist die Isolation der Sandbox — nicht der Geheimnis-Speicher —, was zwischen deinen Anmeldedaten und allem anderen steht, das dort läuft. Das deckt sich damit, wie der GitHub-Token in der Sandbox funktioniert, und ist der Grund, warum diese Einträge nur auf dich begrenzt sind statt mit der Organisation geteilt. Es ist auch das, was einen [BYO-Agenten](/de/platform/agents/external-agent) überhaupt möglich macht: Die Provider-Anmeldedaten, mit denen er sein Modell erreicht, sind eines dieser Geheimnisse. ## Wo das hingehört Umgebungsvariablen & Geheimnisse ist die eine Seite auf Mitglieds-Ebene, die in die Sandbox reicht statt in den Chat — so kommen deine eigenen Schlüssel und deine Konfiguration zu den Agents, die du startest, ohne dass ein Redakteur oder Admin sie für dich setzt. Der Eintrag, den du am häufigsten hinzufügen wirst, sind die Provider-Anmeldedaten für einen [externen BYO-Agenten](/de/platform/agents/external-agent); lies diese Seite neben jener, um beide Hälften zu sehen — wo die Anmeldedaten liegen und wie einem Agenten gesagt wird, sie statt des Plattform-Gateways zu nutzen. Für den Rest deiner persönlichen Einstellungen — Anzeigename, Passwort, eigene Anweisungen — siehe [Einstellungen](/de/platform/member/preferences). # Als App installieren Source: https://tale.dev/docs/de/platform/member/install-as-app Tale ist eine Progressive Web App. Die Installation legt ein Icon ins Dock oder auf den Homescreen, lässt Tale in einem eigenen Fenster ohne Browser-Beiwerk laufen und behält dieselbe Session, die du im Browser hattest. Es gibt keinen separaten nativen Build zum Herunterladen und keine Erweiterung zum Installieren — dieselbe URL, mit der du dich anmeldest, ist dieselbe App, in einer eigenständigen Hülle. Diese Seite deckt die drei Stellen ab, an denen du die Installation auslöst: die Zeile **App installieren** im Profilmenü von Chromium-Browsern, den Teilen-Schritt in iOS Safari und das Installations-Banner, das Android Chrome von selbst zeigt. Einmal installiert, verhält sich Tale identisch; die Installation ändert nur das Beiwerk drumherum. ## Die Profilmenü-Verknüpfung In Chrome, Edge, Brave, Arc und den anderen Chromium-Browsern führt Tales Profil-Dropdown eine Zeile **App installieren**, wenn der Browser bereit ist zu installieren. Öffne das Menü über deinen Avatar oben rechts, scroll am Themen-Wechsler und am Sprach-Wechsler vorbei und klick **App installieren**. Der Browser öffnet seine native Installations-Bestätigung; akzeptier sie, und Tale landet binnen ein, zwei Sekunden in deinem Dock (macOS), deiner Taskleiste (Windows) oder deiner App-Liste (ChromeOS). Die Zeile ist nur da, wenn der Browser sein `beforeinstallprompt`-Event gefeuert hat und die App noch nicht installiert ist. Browser, die dieses Event nicht feuern — Firefox, Safari, alles im privaten Fenster — zeigen die Zeile nicht, also bleibt das Menü einen Eintrag kürzer, statt etwas zu versprechen, was es nicht liefern kann. ## iOS und iPadOS iOS Safari feuert kein `beforeinstallprompt`, also erscheint die Zeile **App installieren** nicht im Menü. Der Installationspfad liegt stattdessen im Teilen-Sheet von Safari. Öffne Tale in Safari, tipp auf das Teilen-Symbol in der Symbolleiste, scroll runter zu **Zum Home-Bildschirm**, und bestätige. Tale erscheint auf deinem Home-Bildschirm mit demselben Icon wie das Browser-Favicon. Tipp drauf, und Tale öffnet sich in einem eigenen Fenster — keine Safari-Adressleiste, keine Tab-Leiste, kein Zurück-Knopf außerhalb dessen, was Tale selbst zeigt. Benachrichtigungen funktionieren genauso wie im Browser-Tab; die Installation ist der einzige Unterschied. Andere iOS-Browser — Chrome, Edge, Firefox auf iOS — sind unter der Haube Safari und haben keinen eigenen Zum-Home-Bildschirm-Eintrag. Der Safari-Pfad ist der einzige iOS-Installationspfad, der eine echte eigenständige App erzeugt. ## Android Android Chrome regelt die Installation an zwei Stellen. Die erste ist dieselbe Zeile **App installieren** in Tales Profilmenü, identisch zum Desktop-Ablauf. Die zweite ist Chromes eigenes Installations-Banner — eine einzeilige Leiste, die von unten auf der Seite hochfährt, bei Sites, die der Browser für installierbar hält. Tipp **Installieren** im Banner, bestätige im System-Sheet, und Tale landet auf deinem Home-Bildschirm. Wenn du das Banner einmal weggewischt hast, kommt es meist eine Weile nicht wieder. Die Profilmenü-Verknüpfung funktioniert unabhängig davon, ob das Banner gezeigt wurde oder nicht. Andere Android-Browser — Firefox, Samsung Internet, Brave — haben jeweils ihren eigenen Installationspfad im Browser-Menü, typischerweise beschriftet mit **App installieren** oder **Zum Home-Bildschirm**. ## Nach der Installation Tale in einem PWA-Fenster ist dasselbe Tale wie in einem Browser-Tab. Die Session, die Chats, die Wissensdatenbank, die Agents — alles davon ist dieselbe Oberfläche. Die Unterschiede sind kosmetisch und klein: kein Browser-Beiwerk um das App-Fenster, ein Icon im Launcher, und auf den meisten Plattformen merkt sich das Fenster Größe und Position zwischen Starts. Die Deinstallation folgt der Plattform-Konvention. Auf macOS zieh das Icon aus dem Dock; auf Windows rechtsklicke und deinstallier; auf iOS und Android halt das Icon gedrückt und entferne es. Die Deinstallation räumt die PWA-Hülle weg, aber nicht die Session — meld dich wieder über den Browser an, und deine Daten sind dort, wo du sie gelassen hast. ## Wann du dazu greifst Die Installation lohnt sich, sobald du Tale jeden Tag öffnest und willst, dass es sich wie eine deiner Apps anfühlt statt wie einer deiner Tabs. Installier auch, wenn du das Chat-Fenster auf einem virtuellen Desktop oder in einem Stage-Manager-Slot fixieren willst, den Browser-Tabs nicht respektieren würden. Lass die Installation aus, wenn du dich von vielen Maschinen anmeldest und den Browser-Tab bevorzugst — Tale funktioniert so oder so gleich. Die benachbarte Lektüre ist [Mitglieds-Übersicht](/de/platform/member/overview) — sie ist die Karte dessen, was der Rest der Mitglieder-Oberfläche abdeckt, sobald Tale in deinem Dock sitzt. # Projekte Source: https://tale.dev/docs/de/platform/projects/overview Ein Projekt ist ein geteilter Arbeitsbereich, der alles bündelt, was ein Stück Arbeit braucht — die Chats, die Referenzdateien, die Anweisungen, das Aufgaben-Board und die Diskussionen —, damit der Kontext der Arbeit folgt, statt in jeden Chat neu kopiert zu werden. Wo ein einzelner Chat eine Frage beantwortet, ist ein Projekt der Ort, an dem ein Team einen Kunden, einen Launch oder eine länger laufende Untersuchung in Bewegung hält. <Frame caption="Das Aufgaben-Board eines Projekts — einer der acht Tabs, die jedes Projekt trägt."> ![Ein Kanban-Aufgaben-Board im Projekt Website-Relaunch mit sieben Aufgabenkarten, verteilt über die Spalten Backlog, Zu erledigen, In Bearbeitung, In Prüfung, Erledigt und Abgebrochen.](/images/platform/projects-task-board.webp) </Frame> ## Die Teile eines Projekts Jedes Projekt öffnet auf derselben Tab-Leiste: **Allgemein** (Name, Beschreibung, Freigabe und die letzten Chats), **Chats** (deine Chats im Projekt plus die mit ihm geteilten), **Diskussionen** (Themen-Threads für das ganze Team), **Aufgaben** (das Board, mit der Ansicht **Aufgaben-Metriken**), **Anweisungen** (Kontext, der für jeden Chat im Projekt gilt), **Wissen** (die Dateien des Projekts, in einem Ordnerbaum), **Agenten & Modelle** (welche Agenten und Modelle Mitglieder hier sehen) und **Secrets**. In das Projekt installierte Apps hängen ihre eigenen Tabs dahinter an. ## Seiten in diesem Bereich <CardGroup cols="2"> <Card title="Projekt-Konzepte" icon="compass" href="/de/platform/projects/concepts"> Das mentale Modell — was ein Projekt besitzt, wann es einen Einzel-Chat schlägt und wie die Freigabe funktioniert. </Card> <Card title="Dateien verwalten" icon="folder-open" href="/de/platform/projects/manage-files"> Der Wissen-Tab — Dateien in Ordner hochladen, der Index-Status und wie Projektdateien auf das Projekt begrenzt bleiben. </Card> <Card title="Agenten und Modelle" icon="bot" href="/de/platform/projects/project-agents"> Kuratieren, welche Agenten und Modelle in einem Projekt erscheinen — Empfohlen gegenüber Eingeschränkt. </Card> <Card title="Diskussionen" icon="messages-square" href="/de/platform/projects/discussions"> Team-Gespräche in Threads, mit Kategorien, Lebenszyklus und Agenten, die eine @-Erwähnung entfernt sind. </Card> <Card title="Aufgaben-Automatisierung" icon="workflow" href="/de/platform/projects/task-automation"> Board-Aufgaben an Agenten übergeben — die Ausführungsschleife, das Review-Gate und die Leitplanken. </Card> <Card title="Backlog" icon="gauge" href="/de/platform/projects/backlog"> Vorgeschlagene Aufgaben, die eine Automatisierung oder ein Teammitglied hereinsynchronisiert hat — mit Starten aufs Board holen oder mit Schließen abhaken. </Card> </CardGroup> ## Wo das hingehört Projekte liegen in der Sidebar neben dem Chat, und die Übergabe ist natürlich: Eine Frage beginnt im Chat, erweist sich als größer als ein Chat und zieht in ein Projekt um — die Composer-Aktion **In Projekt verschieben…** trägt einen bestehenden Chat hinüber. Wenn Projekte neu für dich sind, starte mit den [Projekt-Konzepten](/de/platform/projects/concepts) für das Modell und geh dann [Projekte nutzen](/de/tutorials/member/use-projects) an einem frischen Projekt von Anfang bis Ende durch. # Projekt-Dateien verwalten Source: https://tale.dev/docs/de/platform/projects/manage-files Der **Wissen**-Tab eines Projekts ist der geteilte Dateibereich, den jeder Chat im Projekt erreichen kann. Lade eine Datei einmal hoch, und jeder Chat im Projekt — und jeder Agent, der darin läuft — kann sie ohne erneutes Hochladen lesen. Diese Seite deckt den Ordnerbaum, den Upload-Mechanismus, das Anheften und die Grenzen ab. Der Wissen-Tab ist nicht die org-weite Wissensdatenbank im Sinn von [Dokumente](/de/platform/knowledge/documents). Seine Dateien sind auf ein Projekt begrenzt und tauchen weder in der org-weiten Bibliothek noch in `@`-Pickern ausserhalb des Projekts noch über WebDAV auf; das Projekt zu löschen löscht die Dateien. Für org-weites Referenzmaterial nutz [Dokumente](/de/platform/knowledge/documents) und bind sie an Agents. <Frame caption="Der Wissen-Tab — der Dateibaum des Projekts; jede Datei bleibt auf dieses Projekt begrenzt und ist für die Suche indexiert."> ![Der Wissen-Tab des Projekts Website relaunch mit zwei indexierten Dateien im Dateibaum, einem Neuer-Ordner-Button und der Dropzone zum Hinzufügen von Dateien.](/images/platform/project-knowledge-files.webp) </Frame> ## Ordner Projekt-Dateien liegen in einem Ordnerbaum. **Neuer Ordner** legt einen Ordner auf der Wurzelebene an; das Ordner-Plus-Symbol auf einer Ordnerzeile erstellt einen Unterordner. Klick einen Ordner an, um ihn auszuwählen — der Drop-Bereich wechselt zu _Datei zu „…" hinzufügen_ und Uploads landen darin. Einen Ordner zu löschen löscht alles darin, inklusive der Einträge im Retrieval-Index; die Bestätigung sagt das, bevor irgendetwas passiert. Ordner hier sind projekt-gebunden: ein gleichnamiger Ordner in der org-weiten Dokumentbibliothek ist ein anderer Ordner. ## Ein durchgespielter Upload Öffne das Projekt, klick **Wissen**, wähl den Zielordner (oder keinen für die Wurzel) und zieh Dateien auf den Drop-Bereich. Die Zeile erscheint im Baum und löst zu **Indexed** auf, sobald das Retrieval sie aufgenommen hat. Derselbe Upload ist nun aus jedem Chat erreichbar, den das Projekt besitzt: Sende eine Nachricht, die das Thema referenziert, und der Agent ruft sie ab — oder tippe `@` im Composer und hefte die Datei oder gleich einen ganzen Ordner an den Turn. ## Ersetzen und Löschen Eine Datei zu ersetzen lädt eine neue Kopie unter demselben Namen hoch; die frühere Version wandert in die Versions-History des Projekts. Zitate aus früheren Chats verweisen weiterhin auf die Version, die aktiv war, als der Chat sie referenzierte. Eine Datei zu löschen entfernt sie sofort aus dem Picker; bestehende Chats behalten ihre Zitate, aber die darunterliegende Datei wird mit dem Rest der Aufbewahrungs-Kohorte des Projekts in den [Papierkorb](/de/platform/admin/governance/trash) verschoben. ## Grössenlimits Pro-Datei- und Pro-Projekt-Limits werden von der Org unter [Richtlinien und Limits](/de/platform/admin/governance/policies-and-limits) gesetzt. Ein Pro-Datei-Limit zu treffen scheitert den Upload mit einem Toast; ein Pro-Projekt-Limit zu treffen scheitert den Upload mit einem anderen Toast, der die Richtlinie benennt. Mitglieder, die ein Limit treffen, können es nicht selbst anheben — ein Admin justiert die Richtlinie, oder der Projektbesitzer löscht ältere Dateien. ## Auftauchen in Chats Ein Chat, der in einem Projekt gestartet wird, hat automatisch Zugriff auf jede Datei im Wissen-Tab des Projekts. Das Retrieval-Tool des Agents sieht Projekt-Dateien neben jeglichen agent-gebundenen Wissensquellen. Zitate aus Projekt-Dateien sind auf den Chat begrenzt, der sie erzeugt hat — einen Chat ausserhalb des Projekts zu teilen bewahrt die Zitate, aber der Betrachter kann nicht zur Quelle durchklicken, ausser er ist auch im Projekt. Anheften mit `@` verengt einen einzelnen Turn: `@Datei` heftet eine Datei an, `@Ordner` einen Ordner samt allem darunter (der Picker bietet in Projekt-Chats die Ordner des Projekts an, überall sonst die org-weiten Ordner). Angeheftete Dateien werden zusätzlich in die Sandbox des Agents unter `/user/uploads` geliefert — Coding-Agents wie Claude Code öffnen also die echten Bytes, statt nur Retrieval-Schnipsel zu zitieren. ## Wo das hineinpasst Dateien verwalten ist die operative Seite für den Wissen-Tab — die konzeptuelle Rahmung liegt in den [Projekt-Konzepten](/de/platform/projects/concepts), und das agent-gebundene Äquivalent über die ganze Org ist [Dokumente](/de/platform/knowledge/documents). Wenn du dich dabei ertappst, dieselben Dateien in viele Projekte erneut hochzuladen, ist das das Signal, sie in die [Dokumente](/de/platform/knowledge/documents) zu verschieben und stattdessen einen Agent daran zu binden. # Projekt-Konzepte Source: https://tale.dev/docs/de/platform/projects/concepts Ein Projekt ist die Einheit, zu der Tale greift, wenn ein Arbeitsvorhaben dieselben Dateien, dieselben Anweisungen und dieselben Arbeitsflächen über viele Chats und viele Personen hinweg braucht. Diese Seite gibt dir das mentale Modell — lies sie, bevor du dein erstes Projekt erstellst, und komm zurück, wenn du entscheidest, ob ein wachsender Chat in eines befördert werden soll. <Frame caption="Der Tab Allgemein — Identität, Freigabe und die Statistik-Leiste sind die Eingangstür des Projekts."> ![Der Tab Allgemein des Projekts Website-Relaunch mit den Feldern für Name und Beschreibung, dem Freigabe-Bereich, in dem Organisationsweit als verantwortliches Team steht, und einer Statistik-Leiste, die zwei Dateien, keine Chats und Organisationsweit zeigt.](/images/platform/project-general-tab.webp) </Frame> ## Was ein Projekt besitzt **Chats**, die im Projekt gestartet werden, tragen seinen Kontext automatisch. Sie bleiben deine, bis du an einem Chat **Mit Projekt teilen** umlegst — der Chats-Tab teilt sich entsprechend in **Deine Chats** und **Mit Projekt geteilt**. Das Teilen eines Chats blendet deine persönlichen Erinnerungen und Anweisungen aus den Antworten aus, die andere Mitglieder sehen. **Anweisungen** sind Kontext, der für jeden Chat im Projekt gilt — die Rahmung, die Randbedingungen und das Vokabular der Arbeit —, damit niemand sie pro Chat neu einfügt. **Dateien** auf dem Tab **Wissen** sind Referenzmaterial, aus dem jeder Chat im Projekt schöpfen kann — abgelegt in einem Ordnerbaum, den du einmal befüllst, statt sie pro Chat neu anzuhängen. Sie bleiben auf dieses Projekt begrenzt und tauchen weder in der org-weiten Bibliothek noch in `@`-Pickern außerhalb davon auf — siehe [Dateien verwalten](/de/platform/projects/manage-files). **Aufgaben und Diskussionen** machen das Projekt zu einem Ort, an dem Arbeit läuft, statt nur besprochen zu werden: ein Board mit Status und [Automatisierung](/de/platform/projects/task-automation) sowie [Diskussionen in Threads](/de/platform/projects/discussions) für Entscheidungen. **Agenten & Modelle** ist eine Kuratierungsfläche: welche Agenten und Modelle Mitglieder in diesem Projekt zuerst sehen — oder überhaupt sehen ([Agenten und Modelle](/de/platform/projects/project-agents)). ## Erstellen und Identität **Projekt erstellen** fragt nach einem Namen und einem **Projektkürzel** — dem Präfix für Aufgaben-IDs wie `WR-1`. Das Kürzel steht fest; nach dem Erstellen des Projekts lässt es sich nicht mehr ändern. Beschreibung, besitzendes Team, Icon und Farbe bleiben später auf dem Tab **Allgemein** änderbar, wo die vereinheitlichten Buttons **Speichern** und **Verwerfen** in der Tab-Leiste sitzen. ## Das Freigabe-Modell Geteilt wird pro Team, nicht per Einzeleinladung. Ein Projekt steht standardmäßig auf **Organisationsweit**; wählst du ein besitzendes Team, gilt es nur für dieses Team, und weitere Teams kommen auf dem Tab Allgemein dazu. Org-Admins haben immer Zugriff. Umbenennen, Archivieren und Löschen liegen im Zeilenmenü der Projektliste — beim Löschen fragt Tale, was mit dem Inhalt passiert: Dateien und Chats lösen (sie werden zu Bibliotheksdokumenten und persönlichen Chats) oder sie mitlöschen. ## Wann du danach greifst | Nimm … wenn | Projekt | Einzel-Chat | | ----------------------------------------------------------- | ------- | ----------- | | Dieselben Dateien gelten über viele Chats | ✓ | | | Dieselben Anweisungen gelten über viele Chats | ✓ | | | Mehrere Personen arbeiten am selben Vorhaben | ✓ | | | Die Arbeit hat Aufgaben, Verantwortliche und Entscheidungen | ✓ | | | Die Frage ist einmalig | | ✓ | Ein Einzel-Chat ist die richtige Form, um eine Antwort einmal zu erkunden. In dem Moment, in dem der Kontext den Chat überleben soll, zieh um — die Composer-Aktion **In Projekt verschieben…** trägt einen bestehenden Chat in ein Projekt. ## Wo das hingehört Projekte sind die Naht, an der Chats, Wissen und Aufgaben-Automatisierung zusammentreffen. Die natürliche nächste Lektüre ist [Projekte nutzen](/de/tutorials/member/use-projects) — ein frisches Projekt von Anfang bis Ende; die Tab-Seiten in diesem Bereich vertiefen [Dateien](/de/platform/projects/manage-files), [Agenten und Modelle](/de/platform/projects/project-agents) und [Diskussionen](/de/platform/projects/discussions). # Diskussionen Source: https://tale.dev/docs/de/platform/projects/discussions **Diskussionen** sind Gespräche in Threads, die beim Projekt leben, neben seinen Chats und Aufgaben. Nutze sie so, wie ein Team ein Diskussionsboard nutzt: ein Thema eröffnen, es durchsprechen, es auflösen — mit den Agenten des Projekts eine @-Erwähnung entfernt. Sie verwenden die Nachrichtenfläche des Chats wieder, eine Diskussion liest und schreibt sich also wie ein Chat, aber sie gehört dem Projekt, und jedes Projektmitglied sieht sie, nicht nur die Person, die sie verfasst hat. <Frame caption="Der Diskussionen-Tab — jede Zeile trägt ihre Kategorie und ihren Lebenszyklus-Status."> ![Der Diskussionen-Tab des Projekts Website-Relaunch mit zwei offenen Diskussionen, eine mit der Kategorie Fragen & Antworten, eine mit der Kategorie Entscheidungen.](/images/platform/project-discussions-list.webp) </Frame> ## Eine Diskussion eröffnen Klicke auf **Neue Diskussion**, gib ihr einen **Titel**, wähle eine **Kategorie** und schreib die Eröffnungsnachricht. Die Kategorien halten das Board überschaubar: **Allgemein**, **Fragen & Antworten**, **Ideen**, **Entscheidungen**, **Ankündigungen**, **Zeigen & Erzählen** und **Umfragen**. Antworten funktionieren wie jedes Nachrichtenfeld — der Platzhalter sagt es selbst: **Antworten… mit @ ein Teammitglied oder einen Agenten erwähnen**. ## Menschen zuerst, Agenten auf Zuruf Diskussionen sind menschenzentriert. Dein Beitrag wird immer als Nachricht zwischen Menschen gespeichert; ein Agent antwortet nur, wenn du einen dazuholst. - **Erwähne einen Agenten mit @** in einer Nachricht, und dieser Agent antwortet im Thread — dasselbe Routing und dieselbe Generierung wie im Chat, sichtbar für alle im Projekt. - Ohne @-Erwähnung wird nichts gerufen. Eine Diskussion kann ihr ganzes Leben lang laufen, ohne dass je ein Agent spricht. Das macht Diskussionen zur richtigen Fläche für Entscheidungen, die eine menschliche Spur brauchen und nur gelegentlich KI-Zuarbeit — bitte den Agenten mitten im Thread um die Daten und entscheide dann rund um sie. ## Lebenszyklus Die Kategorie einer Diskussion sagt, was sie ist; ihr Status sagt, wo sie steht: - **Offen** — aktiv, der Standard. - **Gelöst** — die Frage ist beantwortet oder die Entscheidung gefallen. **Wieder öffnen** holt sie jederzeit zurück. - **Gesperrt** — keine weiteren Antworten; der Composer ist deaktiviert und zeigt einen Sperrhinweis. **Entsperren** kehrt es um. Auflösen ist Buchführung, kein Archiv — gelöste Diskussionen bleiben im Tab lesbar und durchsuchbar. ## Aus einer Diskussion wird Arbeit **Aufgabe erstellen** erzeugt aus der Diskussion eine Aufgabe auf dem Projekt-Board, zurückverlinkt auf das Gespräch, aus dem sie kam — eine in einer Diskussion gefallene Entscheidung wird nachverfolgbare Arbeit, ohne sie abzutippen. Die Diskussion merkt sich die Umwandlung: Sie zeigt **In Aufgabe umgewandelt** mit einem Link **Aufgabe ansehen**, und sie lässt sich nur einmal umwandeln. ## Wo das hingehört Diskussionen füllen die Lücke zwischen einem persönlichen Chat (eine Person und ein Agent) und dem Aufgaben-Board (bereits entschiedene Arbeit): Sie sind der Ort, an dem ein Team entscheidet. Die Aufgaben, die sie erzeugen, fließen wie jede andere Board-Aufgabe in die [Aufgaben-Automatisierung](/de/platform/projects/task-automation), und die @-Erwähnungsmechanik entspricht [Agenten im Chat](/de/platform/chat/agents-in-chat). # Aufgaben-Automatisierung Source: https://tale.dev/docs/de/platform/projects/task-automation Eine Board-Aufgabe einem KI-Agenten zuzuweisen setzt ihn in Bewegung. Das **Task-Ops-Paket** — elf dateibasierte Workflows, die jede Organisation erhält — deckt den gesamten Lebenszyklus ab: Triage, Ausführung, Review, Eskalation, SLA-Durchsetzung und Aufräumen. Jeder Workflow ist eine schlichte JSON-Datei, die deiner Organisation gehört: Schwellwerte anpassen, Prompts bearbeiten oder einzelne Trigger direkt am Workflow deaktivieren. Eine Aufgabe, die eine Automatisierung vorschlägt, liegt im [Backlog](/de/platform/projects/backlog), bis ein Mensch sie startet — von diesem Moment an ist sie eine Board-Aufgabe wie jede andere und tritt in die Schleife unten ein. <Frame caption="Das Aufgaben-Board eines Projekts — eine Karte einem Agenten zuzuweisen startet die Schleife unten."> ![Ein Kanban-Aufgaben-Board im Projekt Website-Relaunch mit sieben Aufgabenkarten, verteilt über seine Status-Spalten, von Backlog und Zu erledigen über In Prüfung bis Erledigt und Abgebrochen.](/images/platform/projects-task-board.webp) </Frame> ## Die Ausführungsschleife 1. **Zuweisen** an einen Agenten (oder die _Triage für Unzugewiesenes_ bewertet und routet neue Aufgaben automatisch — sichere Treffer werden direkt zugewiesen, der Rest bekommt einen Vorschlags-Kommentar). 2. Der Agent **bestätigt** (Aufgabe wandert nach _In Bearbeitung_), arbeitet in seinem eigenen Aufgaben-Thread mit den Task-Werkzeugen und postet sein Ergebnis als Kommentar. 3. Die Aufgabe parkt bei **_In Prüfung_** — Agenten können niemals _Erledigt_ setzen; diese Regel wird serverseitig erzwungen, unabhängig von jeder Workflow-Konfiguration. 4. Ein Mensch **gibt frei** (der einzige automatisierte Weg zu _Erledigt_) oder **fordert Änderungen an** — das Feedback reaktiviert denselben Agenten im gemeinsamen Thread und öffnet ein frisches Review-Gate. Reviews lassen sich aus dem Aufgaben-Detail oder direkt aus der Inbox beantworten. Fehlschläge rollen die Aufgabe mit erklärendem Kommentar nach _Zu erledigen_ zurück. Hat eine zerlegte Wurzel-Aufgabe Unteraufgaben, wartet die übergeordnete Aufgabe, bis die letzte Unteraufgabe schließt, und rollt dann nach _In Prüfung_ hoch. ## Erwähnungen, Abhängigkeiten, Fristen - **Erwähne einen Agenten mit @** in einem Aufgabenkommentar oder in der Beschreibung, und er liest den erwähnenden Text und handelt. Ein getipptes `@` öffnet eine Autovervollständigung über Mitglieder und die Agenten des Projekts; der Composer zeigt vorab, ob jeder erwähnte Agent wirklich antworten wird (Automatisierung aus, Budget aufgebraucht, pausiert). Das Bearbeiten einer Beschreibung löst nur neu hinzugekommene Erwähnungen aus, und was die Automatisierung selbst schreibt, löst nie jemanden aus. - Schließt ein **Blocker**, bekommen abhängige Aufgaben einen Hinweis auf die verbleibenden Blocker; vollständig entblockte Agenten-Arbeit startet automatisch neu, menschliche Arbeit bekommt eine Benachrichtigung in die Inbox. - **Fälligkeitsdaten** treiben eine SLA-Leiter: eine 24-Stunden-Warnung, ein Überfällig-Anstoß, dann eine menschliche Eskalation an die Person, die das Projekt erstellt hat, und die Org-Admins — bleibt die Aufgabe überfällig, wiederholt sie sich noch einmal. Jede Stufe feuert höchstens einmal; das Verschieben der Frist nach hinten setzt die Leiter zurück. ## Leitplanken Jeder Agenten-Lauf — Zuweisung, Erwähnung, Überarbeitung, Eskalation, extern — passiert dasselbe Zulassungstor: - **Budgets** (pro Agent, monatlich): An der Warnschwelle bekommt der Agent eine Sparsamkeits-Anweisung, und die Admins werden einmal benachrichtigt; an der Pausenschwelle werden neue Läufe abgewiesen. Budgets setzen sich am Monatswechsel zurück. - **Parallelitäts-Deckel** (pro Agent und org-weit): Überzählige Läufe warten in der Schlange und starten automatisch, sobald ein Platz frei wird. - **Sicherung pro Aufgabe**: Mehr als die konfigurierten Läufe pro Stunde auf einer Aufgabe pausieren die Automatisierung auf dieser Aufgabe, bis ein Mensch ihren Status ändert. Org-weite Deckel (Lauf-Parallelität, Läufe pro Aufgabe und Stunde) sind feste Plattform-Standardwerte; Budget und Parallelität pro Agent liegen in der Konfiguration des Agenten. ## Den richtigen Bearbeiter wählen Nicht jede Aufgabe gehört auf einen Coding-Agenten. Als Faustregel: | Aufgabenform | Zuweisen an | | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Recherche, Texte, Zusammenfassungen, persönliche Liefergegenstände | Eine **Person** — schalte die Sichtung unzugewiesener Aufgaben in persönlichen Projekten ab, damit Agents sie nicht automatisch übernehmen | | Allgemeine Automatisierung mit Plattform-Tools (Kommentare, Workflows, Integrationen) | Einen **Agent** (Plattform-Tool-Schleife) | | Repository-Arbeit — Bugs, Features, Refactorings, PRs | Einen **Coding-Agenten** mit dem passenden Dispatch: tale-daemon (`runtime`) für Git-Arbeitsbereiche, Durable-Sandbox wo konfiguriert — oder akzeptiere, dass Sandbox-only-Coding-Agenten auf dem Board die Plattform-Schleife nutzen, bis du diese Felder ergänzt | Die Bearbeiter-Auswahl gruppiert **Agents** und **Coding-Agenten** getrennt und zeigt zu jedem Coding-Agenten einen einzeiligen Dispatch-Hinweis. Bild-Agenten tauchen in der Aufgaben-Bearbeiterliste nicht auf. ## Der Notausschalter Die Governance-Richtlinie `task_automation` trägt den Hauptschalter: Schaltest du sie aus, stoppt der Ausführungspfad — laufende Arbeit endet noch, Neues startet nicht. Der Schalter ist Admins vorbehalten und wird auditiert; auf einer selbst gehosteten Instanz ist die Richtlinie eine der Governance-Konfigurationsdateien der Organisation, neben den Limits, die [Richtlinien und Limits](/de/platform/admin/governance/policies-and-limits) behandelt. ## Wo das hingehört Aufgaben-Automatisierung macht aus dem Projekt-Board eine Delegationsfläche statt einer To-do-Liste: Ein Mensch weist zu oder gibt frei, das Paket erledigt alles dazwischen, und das Review-Gate sorgt dafür, dass _Erledigt_ eine menschliche Entscheidung bleibt. Die natürliche nächste Lektüre ist [Backlog](/de/platform/projects/backlog) dafür, wie vorgeschlagene Arbeit in die Schleife gelangt, und [Der Workflow-Editor](/de/platform/automations/editor) fürs Feintuning der paketeigenen Workflows. # Projekt-Backlog Source: https://tale.dev/docs/de/platform/projects/backlog Eine Aufgabe im Status **`backlog`** ist vorgeschlagene Arbeit, für die sich noch niemand verpflichtet hat — meist eingespeist von einer Automatisierung wie [GitHub-Issues sichten](/de/platform/automations/builtin). Sie liegt in der **linken Spalte** auf dem Board und im **obersten Abschnitt** in der Liste, mit derselben Karte, demselben Detail-Sheet, demselben Status-Picker und demselben Zuweisungs-Picker wie jeder andere Status. [Aufgaben-Automatisierung](/de/platform/projects/task-automation) behandelt, was passiert, sobald eine Aufgabe **Zu erledigen** erreicht und in die Zuweisungs-Schleife eintritt. ## Eine synchronisierte Aufgabe GitHub-Issues sichten schlägt eine Aufgabe pro umsetzbarem offenem Issue vor, verankert am Issue, sodass ein späterer Abgleich sie nie doppelt anlegt: Der Titel lautet `#<Nummer> <Titel>` — zum Beispiel `#482 Login-Button auf Safari verschoben` —, die Beschreibung beginnt mit der eigenen GitHub-URL des Issues, und ihre Labels spiegeln die GitHub-Labels des Issues. Eine Aufgabe, die du vom Board aus mit dem Standardstatus anlegst, startet bei **Zu erledigen**; wähle **Backlog** im Erstellungsformular, wenn du selbst einen Vorschlag ablegen willst. ## Arbeit weiterbewegen Es gibt keine Backlog-spezifischen Buttons. Ziehe eine Karte in eine andere Spalte, öffne das Detail-Sheet und wähle einen neuen Status, oder weise einen Owner zu — dieselben Wege wie bei **Zu erledigen** oder **In Bearbeitung**. Auto-Zuweisung und Zuweisungs-Vorschläge von Agenten laufen nur bei **Zu erledigen**, nicht solange die Aufgabe im **Backlog** liegt. Wenn du einen Vorschlag direkt nach **In Bearbeitung** schiebst oder von Hand zuweist, übernimmst du die Verantwortung selbst. Lehne einen Vorschlag ab wie jede andere Aufgabe: Setze den Status im Picker auf **Abgebrochen**. Eine menschliche Stornierung bleibt bestehen — ein späterer GitHub-Abgleich holt einen abgelehnten Vorschlag nicht zurück, solange das Issue auf GitHub offen bleibt. War eine Aufgabe auf dem Board **Erledigt** und jemand öffnet das Issue auf GitHub wieder, setzt der Abgleich die Aufgabe zurück ins **Backlog**. ## Wo das hineinpasst Backlog ist die Eingangsspalte zwischen einer Automatisierung, die Arbeit vorschlägt, und deinem Team, das sich dazu verpflichtet. Die natürliche nächste Lektüre ist [Aufgaben-Automatisierung](/de/platform/projects/task-automation) für das, was bei **Zu erledigen** passiert, oder [Mitgelieferte Automatisierungen](/de/platform/automations/builtin) dafür, was überhaupt Aufgaben vorschlägt. # Agenten und Modelle in einem Projekt Source: https://tale.dev/docs/de/platform/projects/project-agents Der Tab **Agenten & Modelle** eines Projekts entscheidet, welchen Agenten und Modellen Mitglieder begegnen, wenn sie im Projekt chatten. Er erstellt keine neuen Agenten — Agenten entstehen org-weit unter [Agenten](/de/platform/agents/concepts) —, er kuratiert den bestehenden Katalog für den Kontext dieses Projekts, damit ein Mitglied im Picker zuerst die richtigen Werkzeuge für die Arbeit sieht. <Frame caption="Der Tab Agenten & Modelle — je eine Empfohlen/Eingeschränkt-Wahl für Agenten und für Modelle."> ![Der Tab Agenten & Modelle eines Projekts mit zwei Optionsgruppen, Agenten und Modelle, die jeweils einen Modus Empfohlen und einen Modus Eingeschränkt samt Hinzufügen-Button anbieten.](/images/platform/project-agents-models.webp) </Frame> ## Die zwei Modi Agenten und Modelle werden getrennt kuratiert, jeweils mit denselben zwei Modi: - **Empfohlen** — die Einträge deiner Liste werden im Picker nach oben gepinnt; alles andere, was das Mitglied sonst nutzen könnte, bleibt darunter verfügbar. Das ist der Standard und der richtige Modus, um zu lenken, ohne zu blockieren. - **Eingeschränkt** — nur die Einträge deiner Liste sind in diesem Projekt verfügbar. Wer etwas anderes wählt, bekommt eine klare Absage: Der Composer meldet, dass der Agent oder das Modell in diesem Projekt nicht verfügbar ist, und bittet um eine andere Wahl. Die Reihenfolge der Liste ist die Reihenfolge, die Mitglieder sehen, und der erste Eintrag ist der Standard — zieh zum Umsortieren. **Agent hinzufügen** und **Modell hinzufügen** erweitern die Liste. <Warning> Im Modus **Eingeschränkt** sperrt eine leere Liste jedes Mitglied vom Chatten im Projekt aus — es bleibt nichts zum Auswählen übrig. Füge vor dem Speichern mindestens einen Eintrag hinzu oder wechsle zurück zu **Empfohlen**. </Warning> ## Was Mitglieder erleben Im Projekt spiegeln Agenten-Picker und Modell-Picker des Composers die Kuratierung — empfohlene Einträge zuerst, eingeschränkte Einträge ausschließlich. Ein Chat, der mit einem inzwischen unzulässigen Agenten ins Projekt verschoben wird, bricht nicht stumm: Das Senden wird mit dem Hinweis abgewiesen, dass der Agent in diesem Projekt nicht verfügbar ist, und das Mitglied wählt einen erlaubten. Außerhalb des Projekts ändert sich nichts; die Kuratierung gilt nur für Chats, die im Kontext des Projekts laufen. ## Wer es ändern darf Das Bearbeiten des Tabs folgt den Org-Rollen: Zum Speichern braucht es eine Redakteurs- oder Admin-Rolle, und Mitglieder ohne sie sehen das Projekt schreibgeschützt, mit einem Banner, das auf einen Projekt-Redakteur verweist. Änderungen landen über **Speichern** in der Tab-Leiste — derselbe vereinheitlichte Speichern/Verwerfen-Block, den auch die Tabs Allgemein und Anweisungen nutzen. ## Wann du zu welchem Modus greifst | Nimm … wenn | Empfohlen | Eingeschränkt | | ----------------------------------------------------------- | --------- | ------------- | | Der richtige Agent soll die offensichtliche erste Wahl sein | ✓ | | | Mitglieder sollen Zugriff auf den vollen Katalog behalten | ✓ | | | Compliance oder Kosten verlangen eine feste, kurze Liste | | ✓ | | Ein teures Modell darf für diese Arbeit nicht laufen | | ✓ | ## Wo das hingehört Dieser Tab ist die Projekt-Seite der Kuratierung eines Org-Katalogs: Agenten zu bauen — samt Anweisungen und Wissen — ist Aufgabe des Bereichs [Agenten](/de/platform/agents/concepts); zu entscheiden, welche davon dieses Projekt zeigt, ist deine. Wie sich der Picker im Chat verhält, steht in [Agenten im Chat](/de/platform/chat/agents-in-chat). # Entwickler Source: https://tale.dev/docs/de/platform/developer/overview Entwickler ist die In-App-Oberfläche für die Personen, die Tale an den Rest ihres Stacks verdrahten. Sie gruppiert die vier Hebel, die externem Code erlauben, mit Tale zu sprechen, und Tale erlauben, mit externem Code zu sprechen: API-Schlüssel für die REST-Oberfläche, Custom Tools, die die Reichweite eines Agents erweitern, Agent-Webhooks für eingehende Trigger und MCP-Server für die Brücke zu externen Prozessen. Personen mit Entwickler-Rolle sehen dieses Menü; Mitglieder und Redakteure nicht. Diese Übersicht nennt, was jede Seite behandelt, und verweist auf die tiefere Referenz. Entwickler-Rollen-Benutzer landen meist hier an ihrem ersten Tag, richten die Anmeldedaten und Tools ein, die sie brauchen, und kommen wieder, wenn sie den Stack erweitern — einen neuen MCP-Server hinzufügen, einen Schlüssel rotieren, einen neuen Webhook registrieren. ## Was Entwickler abdeckt Die Entwickler-Oberfläche sitzt neben dem Rest der Einstellungen der Organisation, aber mit einem engeren Publikum. Sie setzt voraus, dass du weißt, was eine REST-API ist, wie ein Webhook aussieht und was ein MCP-Server tut — die Seiten erklären die zugrundeliegenden Konzepte nicht neu; sie erklären, wie Tale sie offenlegt. Dieselbe Oberfläche in den Cloud- und Self-hosted-Tabs unterscheidet sich nur in der Deployment-Form; die Oberfläche hier ist identisch. Die Konfigurationsdatei-Entsprechungen einiger dieser Funktionen (Env-Vars, JSON-Konfigurationen für Custom Tools) liegen einen Tab weiter in der Self-hosted-Dokumentation. ## Seiten in diesem Bereich <CardGroup cols="2"> <Card title="API-Schlüssel" icon="key" href="/de/platform/admin/api-keys"> Ein Skript, einen Cron-Job oder einen internen Dienst an Tales REST-API verdrahten. Geteilt mit Admin unter Einstellungen > API-Schlüssel. </Card> <Card title="MCP-Server" icon="server" href="/de/platform/integrations/mcp-servers"> Einen externen MCP-Protokoll-Prozess registrieren und wählen, welche seiner Tools die Agents der Organisation aufrufen dürfen. </Card> <Card title="Agent-Webhook-Trigger" icon="webhook" href="/de/platform/agents/webhook-triggers"> Einen bestimmten Agent von einem externen System bei einem eingehenden POST feuern. </Card> <Card title="Agent-Tools" icon="wrench" href="/de/platform/agents/tools"> Den Toolbelt eines Agents um ein Custom Tool erweitern, das die Agents der Organisation aufrufen können. </Card> </CardGroup> ## Wo das hingehört Entwickler ist die Brücke zwischen Tale und dem Rest der Codebase, die die Organisation fährt. Die natürliche Erstlektüre hängt davon ab, was du verdrahten willst — für ausgehend (etwas innerhalb von Tale ruft nach außen) [Agent-Tools](/de/platform/agents/tools) und [MCP-Server](/de/platform/integrations/mcp-servers); für eingehend (etwas von außen ruft in Tale hinein) [API-Schlüssel](/de/platform/admin/api-keys) und [Agent-Webhook-Trigger](/de/platform/agents/webhook-triggers). # Einen Agent erstellen Source: https://tale.dev/docs/de/platform/agents/create Dieses Tutorial führt vom leeren Dialog **Agent erstellen** zu einem Agent, den du veröffentlichst und nutzt. Das Ergebnis ist ein funktionierender Agent, der seine Domäne kennt, die Tools hat, um auf das zu reagieren, was er liest, und aus jedem Chat deiner Organisation erreichbar ist. Etwa fünfzehn Minuten, wenn ein Modellanbieter schon konfiguriert ist; länger, wenn du erst einen einrichten musst. Das Tutorial nutzt einen Support-Triage-Agent als durchgehendes Beispiel — denselben, den [Agent-Konzepte](/de/platform/agents/concepts) einführt. Ersetze die Domäne frei durch deine eigene; die Schritte hängen nicht am Beispiel. ## Bevor du beginnst Stell sicher, dass zwei Dinge stehen: - Ein Modellanbieter ist unter **Einstellungen > Anbieter** konfiguriert. Cloud-Nutzer bekommen standardmäßig einen; selbst gehostete Betreiber folgen [Konfiguration → Anbieter](/de/self-hosted/configuration/providers). Ohne Anbieter stoppt dich der Dialog: ein Agent braucht ein Modell, um zu laufen. - Du hast die Rolle Redakteur oder höher in dieser Organisation. Prüfe deine Mitgliederzeile unter **Einstellungen > Organisation**, wenn du unsicher bist. ## Schritt 1 — Den Agent erstellen Öffne **Agenten** in der Seitenleiste und klicke auf **Agent erstellen**, dann wähle **Leer** (das Menü bietet auch **Aus Vorlage** und **Datei hochladen** für den Import von Agent-JSON). Der Dialog fragt nach vier Dingen: einem **Name** — der eindeutigen Id für Links und die API, die du später nicht ändern kannst; nutze nur Kleinbuchstaben, Zahlen, Bindestriche und Unterstriche, z. B. `seo-writer` —, einem **Anzeigename**, den Teamkollegen im Chat sehen, einer **Beschreibung** und der **Modell**-Liste. Das erste Modell ist der Standard, der Rest sind Fallbacks; zieh zum Umsortieren oder ergänze jederzeit weitere. Klicke auf **Weiter**, und der Editor öffnet sich auf dem Tab **Allgemein**. <Frame caption="Die Agentenliste — Agent erstellen sitzt oben rechts."> ![Die Agentenliste mit ausgeklapptem chat-Ordner, die die Zeilen Assistant und Automation Assistant mit ihren Standardmodellen und Tool-Anzahlen zeigt.](/images/platform/agents-list-expanded.webp) </Frame> ## Schritt 2 — Die Anweisungen schreiben Öffne **Anweisungen & Modelle**. Das Feld **Systemanweisungen** ist reines Markdown, mit **Prompts durchsuchen** als Start aus der Prompt-Bibliothek der Organisation und Template-Variablen, die zur Laufzeit aufgelöst werden. Drei Ratschläge aus der Praxis: - **Beginne mit der Stimme.** Ein Absatz, der benennt, wer der Agent ist, wem er antwortet und welchen Ton er anschlägt. Das Modell behandelt das als stärkstes Signal. - **Benenne die Ablehnungsfälle explizit.** Drei oder vier Sätze, die sagen, was der Agent ablehnt und was er sagt, wenn er ablehnt. - **Widersteh dem Drang, jedes Verhalten zu spezifizieren.** Lange Anweisungen verwässern in langen Konversationen. Gehört ein Verhalten in Code, stütz dich auf ein Tool; gehört es in Daten, stütz dich auf Wissen. Derselbe Tab hält die Modell-Liste aus dem Dialog — das erste Modell ist das primäre, und jedes Modell darunter ist der nächste Fallback, wenn das darüber nicht verfügbar ist. <Frame caption="Anweisungen & Modelle — oben das System-Prompt, darunter die geordnete Modell-Liste."> ![Der Tab Anweisungen & Modelle des Agenten-Editors mit dem Systemanweisungen-Feld samt Sprach-Tabs und einer geordneten Liste von fünf Modellen mit Umsortier-Reglern.](/images/platform/agent-editor-instructions.webp) </Frame> ## Schritt 3 — Den Wissens-Scope setzen Wechsle zum Tab **Wissen**. Wähle einen **Abrufmodus** — **Tool** lässt den Agent bei Bedarf suchen, **Kontext** injiziert relevantes Wissen in jede Antwort, **Beides** tut beides, **Aus** schaltet die Wissensdatenbank ab. Setz dann den Scope des Durchsuchbaren: **Team-Dokumente einbeziehen**, **Organisationsdokumente einbeziehen** und **Agent-Dokumente**, die du nur für diesen Agent hochlädst. Binde die kleinste nützliche Menge — alles, was du einbeziehst, konkurriert bei jeder Frage um den Abruf. <Frame caption="Der Wissen-Tab — Abrufmodus, Dokument-Scopes und die indizierten Organisationsdokumente."> ![Der Wissen-Tab des Agenten-Editors mit Tool als gewähltem Abrufmodus, eingeschalteten Schaltern für Team- und Organisationsdokumente und der Liste der Organisationsdokumente, in der jede Datei ein Abzeichen Indexiert trägt.](/images/platform/agent-editor-knowledge.webp) </Frame> ## Schritt 4 — Die Tools gewähren Wechsle zum Tab **Tools**. Tools sind einzelne Checkboxen, gruppiert nach Kategorie — Kunden, Produkte, Dateien, Workflows und mehr — plus einer Auswahl für den **Websuche**-Modus ganz oben. Gewähre, was der Agent braucht, und lass den Rest aus; jeder Schalter weitet die Vertrauensgrenze. <Frame caption="Der Tools-Tab — eine Checkliste pro Tool, gruppiert in Kategorie-Karten, von denen jede zählt, was sie gewährt hat."> ![Der Tools-Tab des Agenten-Editors, gescrollt zu den Kategorie-Karten, mit Wissen bei drei von vier angehakten Tools und Dateien bei sieben von sieben, während Konversationen, Diskussionen, Analysen und Aufgaben & Projekte nichts gewährt bekommen haben.](/images/platform/agent-editor-tools.webp) </Frame> <Note> **Code ausführen** (unter **System**) führt Skripte in einer Sandbox aus und untersteht der [Run-Code-Richtlinie](/de/platform/admin/governance/run-code-policy) der Organisation — die Checkbox gewährt das Tool, die Richtlinie entscheidet, was ein Lauf tun darf. </Note> ## Schritt 5 — Sichtbar machen und ausprobieren Zurück auf **Allgemein**: Schalte **Im Chat sichtbar** ein und klicke auf **Speichern**. Eine Meldung bestätigt **Agent gespeichert**. Öffne einen neuen Chat, wähle den Agent in der Agentenauswahl und schick eine Nachricht, die das gewährte Wissen und die Tools fordert. Antwortet der Agent so, wie du es ihm geschrieben hast, bist du fertig; wenn nicht, zeigt der Button **Verlauf** oben rechts im Editor jede gespeicherte Version und lässt dich vergleichen oder wiederherstellen. ## Fehlerbehebung - **Speichern scheitert mit einer Modell-Warnung.** Der Agent hat kein Modell gesetzt — ergänze eines auf dem Tab Anweisungen & Modelle, bevor du speicherst. - **Der Agent taucht nicht in der Agentenauswahl auf.** Bestätige, dass **Im Chat sichtbar** an ist; ist es aus, ist der Agent nur über Delegation erreichbar. Ist es an, prüfe den Abschnitt **Zugriff** — ein Agent, der einem Team zugewiesen ist, ist nur für dieses Team nutzbar. - **Antworten ignorieren das Wissen.** Der Abrufmodus steht womöglich auf **Aus**, die Scope-Schalter sind aus, oder das Dokument ist noch nicht im Zustand **Indiziert** — öffne es über [Dokumente](/de/platform/knowledge/documents) und prüfe. - **Ein Tool-Aufruf wird zur Laufzeit verweigert.** Eine Governance-Richtlinie sperrt das Tool: die Agent-Definition erlaubt es, die Laufzeit verweigert. Prüfe [Richtlinien und Limits](/de/platform/admin/governance/policies-and-limits). ## Wo das gebraucht wird Einen Agent zu erstellen ist der Moment, in dem sich der Rest der Plattform nach Tale anfühlt statt nach generischem Chat. Der natürliche nächste Gang ist [Agent mit Wissen](/de/tutorials/editor/agent-with-knowledge) — dieselbe Form, aber mit einem Ordner voller Dokumente und der Zitat-Pipeline von Anfang bis Ende. Um zu sehen, wie ein Agent eine Teilaufgabe an einen Worker gibt, ist [Arbeit an einen Worker geben](/de/tutorials/editor/delegate-between-agents) der Durchlauf. # Agent-Konzepte Source: https://tale.dev/docs/de/platform/agents/concepts Ein Agent ist die Einheit, zu der Tale greift, wenn dieselbe Frage immer wiederkommt. Er ist die Vier-Knöpfe-Kombination aus Anweisungen, Wissen, Tools und einem Modell — die vier Dinge, an denen du drehst, damit der Agent sich anders verhält. Redakteure und Entwickler bauen sie; Mitglieder und andere Rollen führen sie aus. Diese Seite vermittelt dir das mentale Modell, das der Rest des Abschnitts voraussetzt. Lies sie einmal, bevor du deinen ersten Agent baust; komm zurück, wenn du nicht mehr weißt, ob ein Verhalten, das du ändern willst, in den Anweisungen, im Wissen, in den Tools oder im Modell sitzt. ## Die vier Knöpfe **Anweisungen** sind das System-Prompt — die Prosa, die jede Antwort rahmt. Halte Anweisungen kurz, meinungsstark und konkret; lange Anweisungen verwässern in langen Konversationen. Benenne die Stimme, die Einschränkungen und die Ablehnungsfälle. **Wissen** ist das, was der Agent aus der Wissensdatenbank der Organisation abrufen kann. Ein Abrufmodus entscheidet, ob der Agent bei Bedarf sucht, ob relevante Chunks in jede Antwort injiziert werden, ob beides passiert oder keines — und Scope-Schalter entscheiden, ob Team-Dokumente, Organisationsdokumente und die eigenen Uploads des Agents durchsuchbar sind. Wissen außerhalb dieser Scopes ist für den Agent unsichtbar — es gibt kein implizites Ziehen aus allem, was die Organisation besitzt. **Tools** sind das, was der Agent über Text-Antworten hinaus tun kann. Der Tab **Tools** des Agents ist eine Checkliste pro Tool, gruppiert nach Kategorie — Kunden- und Produktdaten, Dateien, Workflows, Websuche, Code-Ausführung und mehr. Schalte jedes Tool einzeln frei; jedes Tool, das du gewährst, weitet die Vertrauensgrenze, also halte die Liste kurz. **Modell** ist das LLM hinter jeder Antwort. Modelle sind eine geordnete Liste: der erste Eintrag ist das primäre Modell, der Rest sind Fallbacks, die Tale der Reihe nach probiert, wenn das primäre nicht verfügbar ist. Ein Modellwechsel trainiert nichts neu — die anderen drei Knöpfe des Agents sind das „Gedächtnis“ des Modells für den Job. ```mermaid flowchart LR I[Anweisungen] --> A((Agent)) K[Wissen] --> A T[Tools] --> A M[Modell] --> A A --> R[Antwort mit Zitaten] ``` ## Skills als Bündel Ein Skill verpackt Anweisungen — und optional Skripte und Referenzdateien — in ein wiederverwendbares Bündel, das du an einen Agent bindest. Greif zu einem Skill, wenn dasselbe Muster über mehrere Agenten auftaucht: eine Schreibstimme, eine Berechnung, eine mehrstufige Aufgabe. Skills komponieren mit den vier Knöpfen; ein Agent kann bis zu zehn binden und liest jeden zur Laufzeit. Die Skills-Seite beleuchtet den Trade-off zwischen einem Skill und Inline-Anweisungen im Detail: siehe [Agent-Skills](/de/platform/agents/skills). ## Zusammengesetzt — ein Support-Triage-Agent Ein erster nützlicher Agent ist der Support-Triage-Agent: er liest die eingehende Frage, beantwortet, was er kann, und eskaliert den Rest. Die vier Knöpfe: - Anweisungen: ein Absatz Stimme plus drei explizite Ablehnungsfälle. - Wissen: Abruf bei Bedarf über die Produktdokumentation; keine eigenen Uploads für den Agent. - Tools: Websuche und die Konversations-Tools. Keine Code-Ausführung. - Modell: ein fähiges primäres Modell mit einem günstigeren Fallback direkt dahinter. Die Konversation läuft dann so: User-Nachricht → Anweisungen rahmen die Antwort → das Wissens-Retrieval findet die relevanten Chunks → Tools füllen die Lücken → die Antwort landet mit Zitaten. Die Eskalation an einen Spezialisten ist kein Tool-Schalter — sie folgt Delegationsbeziehungen zwischen Agents. Siehe [Agent Workers](/de/platform/agents/delegation). ## Wann du danach greifst Ein einzelner Agent ist die richtige Form, wenn die Konversation in einer Domäne und einer Stimme bleibt. Greif zu einer [Automatisierung](/de/platform/automations/concepts), wenn die Arbeit mehrstufig ist und du Genehmigungen oder Zeitpläne dazwischen willst; greif zu einem rohen Chat (ohne Agent), wenn du eine Antwort selbst erkundest und die Modell-Defaults reichen. | Nutze … wenn | Agent | Roher Chat | Automatisierung | | ----------------------------------------------------------- | ----- | ---------- | --------------- | | Dieselbe Frage kehrt wieder | ✓ | | | | Die Stimme oder die Einschränkungen sind wichtig | ✓ | | | | Du brauchst Genehmigungen oder Zeitpläne zwischen Schritten | | | ✓ | | Du erkundest eine Antwort einmalig | | ✓ | | ## Bau einen Die vier Knöpfe sind das, woraus jeder Tale-Agent besteht: dreh an einem, und du hast das Verhalten des Agents verändert; dreh an dreien, und du hast ein neues Produkt gebaut. Die natürliche nächste Lektüre ist [Bau deinen ersten Agent](/de/tutorials/editor/first-agent-end-to-end) — sie geht die vier Knöpfe auf einer frischen Instanz von Anfang bis Ende durch. # Bildgenerierung Source: https://tale.dev/docs/de/platform/agents/image-generation Jeder Assistent in Tale kann Bilder generieren. Bitte ihn, etwas zu erstellen, zu zeichnen oder zu gestalten, und er erzeugt das Bild inline, so wie ein Anhang in der Antwort erscheint — es gibt keinen separaten Modus, in den du erst wechseln musst. Das funktioniert, sobald der Workspace ein Bildgenerierungs-Modell konfiguriert hat; diese Seite deckt die Verdrahtung ab. Die Mechanik hängt vom darunterliegenden Anbieter ab — Qualität, Kosten und Geschwindigkeit variieren stark. Tales Aufgabe ist, die Fähigkeit dem Agent und dem User zugänglich zu machen; die Aufgabe des Anbieters ist, das Bild zu erstellen. ## Jeden Assistenten um ein Bild bitten Jeder Assistent trägt ein Bild-Tool, zu dem er greift, wenn du ihn um ein Bild, ein Logo oder eine Illustration bittest. Der Assistent ruft das Tool auf, das Bild erscheint inline, und sein Text legt sich um das Ergebnis wie um einen hochgeladenen Anhang. Weil das Tool mit jedem Assistenten ausgeliefert wird, bedient auch der **Auto**-Assistent eine Bild-Anfrage — du musst nicht erst einen spezialisierten Agent wählen. Das Bild kommt vom Bildgenerierungs-Modell des Workspace — dem, das ein Admin unter [Anbieter](/de/platform/admin/providers) eingerichtet und mit **Bildgenerierung** getaggt hat. Pro Agent gibt es nichts zu konfigurieren. Hat der Workspace kein solches Modell, sagt dir der Assistent, dass Bildgenerierung nicht verfügbar ist, statt zu raten — so weiß ein Admin, dass eines fehlt. ## Die dedizierten Bild-Oberflächen Jenseits des Inline-Tools existieren zwei schwerere Formen. Im Agenten-Editor ist das Tool selbst **Bild generieren** unter der Kategorie **Bilder** des Tools-Tabs — entferne den Haken bei einem Agent, der nie Bilder erzeugen soll. Und der Typ eines Agents (auf dem Tab **Allgemein**) lässt sich auf **Bildgenerierung** setzen, was jede Nachricht direkt an ein Bildmodell leitet — die Form hinter dem Katalog-Agent **Bildgenerator**, der Bilder aus Text-Prompts generiert und bearbeitet. Greif zum dedizierten Typ, wenn der ganze Job des Agents Bildarbeit ist; lass allen anderen das Inline-Tool. ## Wie es erscheint Generiert der Agent ein Bild, erscheint es inline neben dem Text des Agents. Hovern zeigt einen kleinen **Bildvorschau**-Chip; Klicken öffnet die Vorschau in voller Größe, mit den Reglern **Vorheriges Bild** und **Nächstes Bild**, wenn die Antwort mehr als eines erzeugt hat. Das Bild liegt im Objektspeicher des Chats neben den Anhängen und erbt die Aufbewahrungsregeln des Chats. ## Kosten und Budget Bildmodelle kosten pro Aufruf mehr als Textmodelle — manchmal das Zehnfache. Die [Richtlinien und Limits](/de/platform/admin/governance/policies-and-limits) der Organisation können Bildkosten pro User, pro Team oder pro Agent deckeln; ein erreichtes Limit erscheint als Meldung, und das Bild wird nicht gerendert. Die Kosten siehst du in der [Nutzungsanalyse](/de/platform/admin/governance/usage-analytics), in derselben Top-Models-Tabelle wie die Textmodelle. ## Wo das hingehört Bildgenerierung hängt an einem einzigen Ding — einem Modell mit dem Tag **Bildgenerierung** im Workspace — und von da an kann jeder Assistent inline ein Bild erzeugen, den **Auto**-Assistenten eingeschlossen. Der Drift-Kandidat hier sind Anbieter- und Modellnamen; leg diese Seite neben die laufende Modell-Liste unter [Anbieter](/de/platform/admin/providers), statt dir konkrete Modell-Strings zu merken. # Gesprächseinstiege Source: https://tale.dev/docs/de/platform/agents/conversation-starters Ein Einstieg ist ein kurzer vorgeschlagener Prompt, den der Agent auf einem leeren Chat-Bildschirm zeigt. Tipp einen an, und der Text fällt in den Composer; der User passt ihn bei Bedarf an und schickt ihn ab. Einstiege sind die kuratierten Einstiegspunkte des Agent-Autors in das, wofür der Agent da ist — diese Seite ist die Autorenseite; wie sie beim User erscheinen, zeigt [Einstiege und Prompts](/de/platform/chat/starters-and-prompts). <Frame caption="Der Tab Gesprächseinstiege — eine geordnete Liste von Prompts mit Sprach-Tabs darüber."> ![Der Tab Gesprächseinstiege des Agenten-Editors mit vier englischen Gesprächseinstiegen samt Zieh-Griffen, Umsortier-Pfeilen und Entfernen-Buttons.](/images/platform/agent-editor-starters.webp) </Frame> ## Einstiege hinzufügen und ordnen Öffne den Agent und wechsle zum Tab **Gesprächseinstiege**. Jeder Einstieg ist ein Prompt mit bis zu 200 Zeichen; **Einstieg hinzufügen** hängt eine Zeile an, bis zu vier pro Agent — lass die Liste leer, um keine Vorschläge zu zeigen. Die Reihenfolge zählt, weil sie die Reihenfolge ist, die User sehen: zieh eine Zeile am Griff oder nutze die Pfeile, und entferne eine über das × in ihrer Zeile. Klicke auf **Speichern** — Einstiege reisen mit der Konfiguration des Agents wie jede andere Einstellung. Schreib Einstiege so, wie ein User wirklich fragen würde: konkret, in der ersten Person, innerhalb der Domäne des Agents. Vier vage Prompts lesen sich schlechter als zwei scharfe. ## Übersetzen Jeder Einstieg hat eine Standardversion (der Tab mit der Markierung **Standard**) und optional eine Übersetzung pro Sprache. Ein Sprach-Tab, dem seine Version noch fehlt, trägt die Markierung **Nicht übersetzt**, und User in dieser Sprache sehen den Standardtext. Wechsle auf einen Sprach-Tab, um Übersetzungen von Hand zu tippen — Übersetzungen überschreiben die bestehenden Zeilen; die Liste selbst (Anzahl und Reihenfolge) gehört der Standardsprache. **Automatisch übersetzen** auf einem Sprach-Tab füllt die fehlenden Versionen in einem Schritt. Die Ergebnisse werden als gewöhnliche, bearbeitbare Strings gespeichert, also justiere danach, wo die Maschinen-Formulierung deine Stimme verfehlt; scheitert die Übersetzung, sagt es eine Meldung, und die Standardtexte bleiben stehen. ## Wo das hingehört Gesprächseinstiege sind die kleinste Oberfläche im Agenten-Bereich — ein paar Sätze pro Stück, aber sie entscheiden, ob der leere Chat-Bildschirm einladend wirkt oder leer. Die Seite, die du daneben legst, ist [Einstiege und Prompts](/de/platform/chat/starters-and-prompts) — sie zeigt, wie sie beim User erscheinen; der Rest des Agent-Verhaltens liegt in [Agent-Konzepte](/de/platform/agents/concepts). # Agent-Webhooks Source: https://tale.dev/docs/de/platform/agents/webhook-triggers Der Tab **Webhook** eines Agents erzeugt eindeutige URLs, an die externe Systeme POSTen und mit dem Agent chatten können — nichts in der UI ist beteiligt. Greif dazu, wenn etwas außerhalb von Tale den Agent antworten lassen soll: ein Slack-Bot, ein Formular-Handler, ein geplanter Job. Diese Seite deckt nur die Webhook-Oberfläche pro Agent ab. Für eingehende Trigger, die einen Workflow statt eines Agents starten, siehe [Workflows → Trigger](/de/platform/automations/triggers); für die volle Entwickler-Oberfläche siehe [Entwickeln → API-Referenz](/de/develop/api-reference). <Frame caption="Der Webhook-Tab — ein aktiver Webhook mit seinem Aktiv-Schalter und dem Zeitpunkt der letzten Auslösung."> ![Der Webhook-Tab des Agenten-Editors mit dem Button Webhook erstellen und einer Tabelle mit einer Webhook-URL, einem Aktiv-Schalter und dem Wert Nie als letzter Auslösung.](/images/platform/agent-editor-webhooks.webp) </Frame> ## Einen Webhook erstellen Öffne den Agent, wechsle zu **Webhook** und klicke auf **Webhook erstellen**. Der Dialog zeigt die neue URL genau einmal — sichere sie, denn das in der URL eingebettete Token wirkt als Zugangsnachweis. Es gibt keinen separaten API-Schlüssel und keine Kopfzeile: wer die URL hält, kann mit dem Agent chatten, also behandle sie wie ein Geheimnis. ## Aufrufen POSTe einen JSON-Body mit einem `message`-Feld; die Antwort ist die Antwort des Agents: ```bash curl -X POST https://tale.yourcompany.com/api/agents/wh/<token> \ -H "Content-Type: application/json" \ -d '{"message": "Hello"}' ``` Drei Felder formen den Aufruf: - **`stream`** — ergänze `"stream": true`, und die Antwort kommt als Server-Sent Events statt als eine JSON-Antwort. - **`threadId`** — ohne startet jeder POST eine frische Konversation; übergib die Thread-Id aus einer früheren Antwort, um eine mit intaktem Kontext fortzusetzen. - **Dateien** — schick `multipart/form-data` mit einem `message`-Feld und einem oder mehreren `file`-Feldern, um Uploads an die Nachricht zu hängen. Die Aktion **Verwendungsbeispiele** jeder Zeile öffnet fertige Beispiele für all das, ausgefüllt mit der echten URL der Zeile. ## Der OpenAI-kompatible Endpunkt Ein an die Webhook-URL angehängtes `/chat/completions` stellt einen ChatCompletion-Endpunkt im OpenAI-Stil bereit, sodass fertige OpenAI-Clients auf einen Agent zeigen können: nutze die Webhook-URL als Basis-URL, einen beliebigen nicht-leeren Wert als API-Schlüssel und eine Modell-Id aus der Modell-Liste des Agents (unbekannte Werte fallen auf den Standard zurück). Datei-Uploads unterstützt nur die Basis-Webhook-URL, nicht dieser Unterpfad. ## Verwalten und widerrufen Die Tabelle zeigt die URL jedes Webhooks, einen **Aktiv**-Schalter und den Zeitpunkt der letzten Auslösung. Einen Webhook abzuschalten pausiert ihn, ohne die URL zu verlieren; ihn zu löschen ist der Widerruf — jedes System, das die URL noch nutzt, verliert den Zugriff, also stell den Ersatz-Webhook bereit, bevor du den alten stilllegst. ## Wo das hingehört Webhooks sind die leichte Integrations-Oberfläche pro Agent — richtig, wenn die Integration „dieser eine Agent beantwortet diese eine Sache“ ist. Für reichere Abläufe mit Schritten und Genehmigungen modelliere die Arbeit als [Automatisierung](/de/platform/automations/concepts) und richte den Aufrufer auf den Webhook-Trigger der Automatisierung — [Automatisierung per Webhook auslösen](/de/tutorials/developer/trigger-automation-via-webhook) geht diese Form von Anfang bis Ende durch. # Agenten-Ordner Source: https://tale.dev/docs/de/platform/agents/categories Agenten sind nach Ordnern gruppiert, und ein Ordner entsteht aus der Id des Agents: ein Agent mit der Id `github/review-pull-requests/pr-reviewer` liegt überall dort, wo Agenten gelistet werden, in einem `github/review-pull-requests`-Ordner. Ordner sind ein organisatorisches Sortierwerkzeug, keine Berechtigungsgrenze — wer einen Agent nutzen darf, regelt der Abschnitt **Zugriff** auf seiner Seite **Allgemein**, unabhängig davon, wo er einsortiert ist. <Frame caption="Die Agentenliste mit ausgeklapptem chat-Ordner — der Ordner ist das Präfix des Slugs, die Zeilen sind seine Agenten."> ![Die Agentenliste mit den Agenten des chat-Ordners — Assistant und Automation Assistant —, jeweils mit Typ-Badge, Standardmodell und Tool-Anzahl.](/images/platform/agents-list-expanded.webp) </Frame> ## Einen Agent in einen Ordner legen Ids mit Ordner kommen von der Plattform, nicht aus dem Erstell-Dialog. Das Feld **Name** im Dialog nimmt eine flache Id — Kleinbuchstaben, Ziffern, Bindestriche und Unterstriche, kein `/` —, sodass ein dort erstellter Agent unabgelegt auf der obersten Ebene landet. Das Ordner-Präfix (`chat/`, `github/review-pull-requests/`) ist Agenten vorbehalten, die die Plattform mitliefert oder installiert: Builtins kommen vorab einsortiert an, und die Installation einer [Automatisierung](/de/platform/automations/concepts) legt ihre Agenten in den Ordner, den ihre Id benennt. Eine Id kann sich später nicht ändern, der Ordner steht also mit dem Erstellen fest. Der Anzeigename ist unabhängig; benenn den Agent frei um, ohne ihn zu verschieben. In der **Agenten**-Liste erscheinen Ordner als eingeklappte Zeilen mit Agentenzahl — klicke einen an, um ihn auszuklappen, und die Breadcrumb-Leiste zeigt, wo du bist. Die eingebauten Agenten kommen voreinsortiert an: die allgemeinen Assistenten unter `chat`; mit einer Automation installierte Agenten liegen im Ordner ihrer Automation. ## Agenten, die mit einer Automatisierung ankommen Die Installation einer [Automatisierung](/de/platform/automations/concepts) sortiert ihre Agenten ein wie alle anderen — der PR Creator und der PR Reviewer aus dem Bundle „GitHub-Issues lösen“ landen in derselben Liste, in dem Ordner, den ihre Id benennt. Einen eigenen Agenten-Store zum Stöbern gibt es nicht: Aus dem [Katalog der Automatisierungen](/de/platform/automations/catalog) kommen gebündelte Agenten, und in der Liste wohnen sie danach. <Note> Die Agentenauswahl im Chat gruppiert nicht nach Ordnern — sie ist eine durchsuchbare Liste mit **Auto** obenauf, die jeden Agent zeigt, der aktiviert und im Chat sichtbar ist; Coding-Agenten stehen in einem eigenen Abschnitt **Coding-Agenten**. </Note> ## Wann du danach greifst | Nutze Ordner, wenn… | Nutze Team-Zugriff, wenn… | | ---------------------------------------------- | ---------------------------------------------------- | | Die Agentenliste lang wird und Ordnung braucht | Ein Agent nur für ein Team nutzbar sein darf | | Abteilungen je einen Satz Agenten besitzen | Du eine Berechtigungsgrenze ziehst, kein Verzeichnis | ## Wo das hingehört Ordner sind die leichteste verfügbare Gruppierung für Agenten — sie sortieren die Liste und den Katalog, mehr nicht. Größere Trennungen liegen woanders: [Projekt-Agenten](/de/platform/projects/project-agents) begrenzen einen Agent auf ein Projekt, und [Richtlinien und Limits](/de/platform/admin/governance/policies-and-limits) regeln, was ein Agent ausgeben oder tun darf. # Agent-Skills Source: https://tale.dev/docs/de/platform/agents/skills Ein Skill ist die Einheit, zu der Tale greift, wenn dasselbe Muster über mehrere Agenten auftaucht. Er ist ein wiederverwendbares Bündel — eine `SKILL.md` mit Anweisungen, plus optionale Skripte, Referenzen und Assets — das in der Skill-Bibliothek der Organisation lebt und das Agenten zur Laufzeit lesen. Binde denselben Skill an drei Agenten, und du pflegst das Verhalten an einer Stelle. Diese Seite vermittelt dir das mentale Modell dafür, wann ein Skill der richtige Zug ist und wann Inline-Anweisungen es sind. Lies sie, bevor du deinen ersten Skill hochlädst; komm zurück, wenn die Anweisungen eines Agents lang werden und du überlegst, ob du sie auslagerst. ## Was ein Skill bündelt Ein Skill wird als Zip mit einer `SKILL.md` an der Wurzel hochgeladen. Das Frontmatter der Datei trägt die Metadaten — Beschreibung, Lizenz, empfohlene Python- oder Node-Versionen — und der Rumpf trägt die Anweisungen. Bündel-Assets liegen unter `scripts/`, `references/` oder `assets/`: Code, den der Agent ausführen kann, wenn er in einer Sandbox arbeitet, und Referenzmaterial, das er bei Bedarf liest. Ein reiner Anweisungs-Skill ist die richtige Form, wenn das Verhalten Stimme oder Einschränkung ist — „zitiere die Quelle immer mit Abschnittsnummer“, „lehne Fragen außerhalb dieses Produkts ab“. Ein Skill mit Skripten ist die richtige Form, wenn das Verhalten eine Berechnung, eine Transformation oder eine mehrstufige Aufgabe ist, die das Modell sonst in Tokens improvisieren müsste. ## An einen Agent binden Ein Skill wird für einen Agent sichtbar, indem du ihn auf dem Tab **Skills** des Agents bindest — **Gebundene Skills** listet die Bibliothek der Organisation mit einer Checkbox pro Skill. Ein Agent kann höchstens zehn Skills binden, und ein Agent ohne Bindungen sieht keinen: es gibt keinen impliziten Rückfall auf organisationsweite Sichtbarkeit. Der Agent liest einen gebundenen Skill zur Laufzeit — die Beschreibung sagt ihm, wann der Skill greift, und dann zieht er Rumpf und Bündeldateien heran. Die Bindung gilt pro Agent: zwei Agenten können denselben Skill binden, und das Lösen ist symmetrisch — die nächste Anfrage läuft ohne ihn. ## Die Bibliothek verwalten Skills zu verwalten verlangt Admin- oder Entwickler-Berechtigungen. Die Bibliothek liegt in den Skills-Einstellungen der Organisation; jeder Skill zeigt dort seine Übersicht, den Anweisungs-Rumpf, den Bündel-Dateibaum und die Änderungsspur **Letzte Änderungen**. **Skill hochladen** ergänzt ein neues Bündel, **Bundle ersetzen** überschreibt ein bestehendes an Ort und Stelle, und **Duplizieren** forkt es unter einem neuen Slug. <Warning> Es gibt kein Versions-Pinning: ein ersetztes Bundle ändert ab der nächsten Anfrage, was jeder gebundene Agent liest, und ein gelöschter Skill entfernt das Bündel von der Platte — jeder aktuell gebundene Agent verliert den Zugriff. </Warning> ## Wann du danach greifst | Nutze … wenn | Skill | Inline-Anweisungen | | ---------------------------------------------------------------------- | ----- | ------------------ | | Das Muster sich über mehrere Agenten wiederholt | ✓ | | | Das Verhalten Skripte umfasst, die das Modell sonst imitieren würde | ✓ | | | Das Verhalten die Stimme eines einzelnen Agents ist | | ✓ | | Die Organisation das Verhalten über eine einzige Änderung steuern soll | ✓ | | | Die Anweisungen des Agents noch auf einen Bildschirm passen | | ✓ | Inline-Anweisungen sind die richtige Form für einen Agent. Skills sind die richtige Form, wenn dasselbe Verhalten in zwei oder drei Agenten auftaucht und die Wartungskosten, ihre Inline-Anweisungen synchron zu halten, zu beißen beginnen. ## Bau einen Skills sind die Abstraktionsebene über den vier Knöpfen — sie lassen dich ein Verhalten einmal ausliefern, und jeder Agent, der es braucht, holt es sich per Bindung. Der natürliche nächste Gang ist [Ein eigenes Tool bauen](/de/tutorials/developer/build-a-custom-tool) — er führt von der leeren Seite zu einem Skill mit Skripten, gebunden an einen Agent. # Externe Agenten Source: https://tale.dev/docs/de/platform/agents/external-agent Tale liefert integrierte **externe Agenten** — **Claude Code**, **Cursor**, **OpenCode**, **Hermes Agent**, **Gemini CLI**, **Codex**, **Pi** und **OpenClaw** —, deren gesamte Runde in einer isolierten Sandbox läuft. Statt der normalen Chat-Schleife wird deine Nachricht an diesen Coding-Agenten übergeben, der in einem frischen Container lebt, Dateien bearbeitet, Befehle ausführt und zurückmeldet. Du sprichst im Chat direkt mit ihm, und er behält dasselbe Arbeitsverzeichnis und denselben Gesprächsverlauf über mehrere Runden, sodass eine Folgeanweisung wie „füge jetzt einen Test dafür hinzu" dort weitermacht, wo er aufgehört hat. Es ist dieselbe Idee, als würde man ein solches Werkzeug auf einer entfernten Maschine ausführen — nur ist die Maschine eine verwaltete Sandbox, die der Workspace kontrolliert. Diese Seite behandelt, wie du sie nutzt, was die Sandbox erreichen kann und was nicht, und wie abgerechnet wird. ## Mit einem Coding-Agenten sprechen Wähle im Chat-Auswahlmenü **Claude Code**, **Cursor**, **OpenCode**, **Hermes Agent**, **Gemini CLI**, **Codex**, **Pi** oder **OpenClaw** und beschreibe eine Aufgabe in normaler Sprache — „schreibe ein kleines Python-CLI und teste es", „klone dieses Repo und behebe den Fehler in Issue #42". Der Agent arbeitet in seiner Sandbox: Er plant, schreibt Dateien, führt Shell-Befehle aus und installiert bei Bedarf Pakete, dann antwortet er mit dem, was er getan hat. Während er arbeitet, siehst du eine Denkanzeige; die Antwort erscheint, wenn die Runde abgeschlossen ist. Du musst nicht warten, bis eine Runde fertig ist. Das Eingabefeld bleibt offen, während der Agent arbeitet: Alles, was du sendest, wartet im Bereich **Wartende Nachrichten** über dem Eingabefeld und wird dem laufenden Agenten bei nächster Gelegenheit übergeben. **Claude Code** übernimmt das mitten in der Runde an der nächsten Werkzeuggrenze — eine Korrektur wie „nimm pnpm statt npm" landet also, während die Arbeit noch läuft. **Cursor**, **OpenCode**, **Codex**, **Pi**, **OpenClaw** und andere One-Shot-Laufzeiten leeren die Warteschlange dagegen an Rundengrenzen. In den Thread selbst gelangt die Nachricht erst bei dieser Übernahme, genau an der Stelle, an der sie gewirkt hat; bis dahin lässt sie sich entfernen (das × in ihrer Zeile). Mit **Stopp** beendest du die aktuelle Runde; noch wartende Nachrichten werden wenige Sekunden später automatisch als nächste Runde gesendet, mit unverändertem Kontext des Agenten. Jeder Chat-Thread wird von einer dauerhaften Sandbox-Sitzung getragen. Folgenachrichten verwenden dieselbe Sitzung und dieselben Dateien wieder, und der Agent setzt seine frühere Überlegung fort, statt bei null zu beginnen. Weil die Sitzung dem Thread gehört, behält der Thread auch seinen Agenten: Die Agentenauswahl bleibt darauf fixiert, und ein Agentenwechsel an anderer Stelle leitet diesen Thread nie um — starte einen neuen Chat, um einen anderen zu verwenden. Wird der Thread gelöscht oder archiviert, wird die Sandbox abgebaut und ihre Ressourcen werden freigegeben. ## Was die Sandbox erreichen kann Die Sandbox startet mit einem leeren Arbeitsverzeichnis und ist standardmäßig abgeriegelt. Dateien und Ordner, die du in deiner Nachricht mit `@` anheftest, werden unter `/user/uploads/` in die Sandbox geliefert, sodass der Agent die echten Bytes öffnet, statt aus einem Retrieval-Schnipsel zu arbeiten. Ausgehender Netzwerkverkehr ist bis auf eine kleine Erlaubnisliste (Paket-Registries und GitHub) gesperrt, sodass der Agent Abhängigkeiten installieren und öffentliche Repositorys klonen, aber keine beliebigen Hosts erreichen kann. Standardmäßig wird das Modell über das Gateway des Workspace angesprochen, nie über einen rohen Provider-Schlüssel — die Sandbox hält für eine Runde nur einen kurzlebigen, budgetbegrenzten Schlüssel. Das ist der _verwaltete_ Anmeldedaten-Modus des Agenten; die _Eigene-Anmeldedaten_-Alternative, die weiter unten behandelt wird, legt bewusst stattdessen deinen eigenen Provider-Schlüssel in die Box. Über diese Abriegelung hinaus kann der Agent jede Integration nutzen, die deine Organisation verbunden hat — das Web über Tavily durchsuchen, eine API aufrufen, eine Datenbank abfragen —, solange diese Integration an den Agenten gebunden ist. Du bindest sie genauso wie bei jedem anderen Agenten: Öffne den **Tools**-Tab des Agenten und wähle sie unter **Gebundene Integrationen** aus. Die Anmeldedaten gelangen dabei nie in die Sandbox; ruft der Agent eine Integration auf, geht die Anfrage an Tale zurück, das den Aufruf mit den gespeicherten Anmeldedaten ausführt und nur das Ergebnis zurückgibt — ein kompromittierter Container kann deine Schlüssel also nicht auslesen. Ein Schreibvorgang läuft nicht stillschweigend ab: Er erscheint als Genehmigungskarte im Chat und wird ausgeführt, sobald du ihn genehmigst. Auch die Daten des Workspace selbst laufen über diesen vermittelten Weg. Auf demselben **Tools**-Tab kannst du zusätzlich **Plattform-Tools** freigeben — Wissenssuche, das Durchsehen und Lesen von Dokumenten, das Speichern von Dateien im Dokumenten-Hub —, und der Agent ruft sie während der Arbeit aus der Sandbox heraus auf. Jeder Aufruf läuft auf der Plattform im Wissensbereich des Agenten und liefert nur das Ergebnis zurück; die Sandbox hält also auch keine Plattform-Anmeldedaten, und ein Speichern im Hub erzeugt dieselbe Genehmigungskarte wie jeder andere Schreibvorgang. Nicht freigegebene Tools sind nicht aufrufbar, und ein BYO-Agent, der ohne Sitzungsschlüssel läuft, hat gar keine Tool-Brücke. GitHub ist die Ausnahme, bei der auch ein Token in die Sandbox gelangt, weil `git` und das `gh`-CLI es lokal brauchen: Verbinde GitHub unter [Integrationen](/de/platform/integrations/overview) und binde es an den Agenten, dann erhält die Sitzung ein begrenztes Token, mit dem der Agent in deinem Namen klonen, pushen und Pull Requests öffnen kann. Alle Anmeldedaten — das GitHub-Token in der Sandbox ebenso wie die vermittelten — sind auf die Sitzung beschränkt, werden bei jedem Aufruf auditiert und beim Ende der Sitzung widerrufen. ## Verwaltete und eigene Anmeldedaten Wie der Agent sein Modell erreicht, ist eine Entscheidung pro Agent, die du im **Anweisungen**-Tab des Agenten unter **Anmeldedaten** triffst. Drei Anmeldedaten-Backends existieren; die UI benennt sie nach der Laufzeit des Agenten. **Gateway-verwaltet (Claude Code, OpenCode, Hermes Agent, Gemini CLI, Codex, Pi und OpenClaw, verwaltet)** ist die Voreinstellung für diese Laufzeiten. Die Plattform prägt für die Runde einen kurzlebigen virtuellen Schlüssel, leitet den Agenten über ihr Gateway, erzwingt die erlaubten Modelle des Agenten aus dem **Providers**-Katalog, erfasst die Nutzung und wendet die Ausgabengrenzen der Organisation an. Die Sandbox hält nie einen echten Provider-Schlüssel. Verwaltete Hermes- und Codex-Runden laufen über eine OpenAI-kompatible Gateway-Route (`OPENAI_BASE_URL` plus virtueller Sitzungsschlüssel in der Sandbox; Codex spricht darüber die OpenAI-Responses-API); verwaltete Gemini-CLI-Runden über die Google-GenAI-kompatible Route des Gateways (`GOOGLE_GEMINI_BASE_URL` plus der virtuelle Sitzungsschlüssel als `GEMINI_API_KEY`); verwaltete Pi-Runden ebenfalls über die OpenAI-kompatible Route, verdrahtet als Pi-Provider-Konfiguration pro Runde, die den virtuellen Sitzungsschlüssel aus der Umgebung referenziert (die Konfigurationsdatei enthält den Schlüssel nie); verwaltete OpenClaw-Runden über die OpenAI-kompatible Route des Gateways mittels einer pro Runde erzeugten Provider-Konfiguration. **Env-verwaltet (Cursor, verwaltet)** gilt für Laufzeiten, die sich mit einem API-Schlüssel authentifizieren, den du am Agenten hinterlegst, nicht über das Gateway. Öffne die **Umgebung**-Seite des Agenten und setze `CURSOR_API_KEY` (oder den Schlüssel, den die Laufzeit deklariert). Das Modell ist eine **Runtime-ID**, die du in der **Modelle**-Liste unter Anweisungen eintippst — `composer-2.5` etwa —, kein Katalogeintrag. Diese Runden fließen **nicht** in die Nutzungsanalyse ein; die Abrechnung liegt bei deinem Cursor-Konto. **Eigene Anmeldedaten (BYO)** nimmt die Plattform aus dem Anfragepfad heraus — für unterstützte Laufzeiten (Claude Code, Cursor, Gemini CLI, Codex, Pi und OpenClaw). **OpenCode ist nur verwaltet** — seine Laufzeitkonfiguration zeigt auf das Plattform-Gateway und authentifiziert sich mit dem Sitzungs-Virtual-Key; BYO ist für OpenCode-Agenten nicht verfügbar. Es wird kein virtueller Schlüssel geprägt; der Agent authentifiziert sich mit Anmeldedaten, die du unter [Umgebungsvariablen & Geheimnisse](/de/platform/member/environment) hinterlegst, und erreicht den Provider direkt. Das Modell wird zu einer rohen Runtime-ID, die du wortwörtlich eintippst, statt zu einem Katalogeintrag. Weil das Gateway umgangen wird, gelten die Modell-Erlaubnisliste, die Ausgabengrenzen und die Nutzungserfassung der Organisation nicht für BYO-Runden — Abrechnung und Limits wandern in dein eigenes Provider-Konto. Wechselst du einen Agenten von verwaltet auf BYO, werden gespeicherte Plattform-Modelle gelöscht, wenn es Katalogverweise waren; du gibst die rohen IDs neu ein. Das verschiebt auch die Vertrauensgrenze. Im gateway-verwalteten Modus hält die Sandbox nur einen budgetbegrenzten Gateway-Schlüssel; bei env-verwaltet oder BYO wird deine echte Anmeldedaten in die Sandbox-Umgebung eingespeist — dieselbe Lage wie beim GitHub-Token in der Sandbox —, sodass jeder Code, den der Agent in der Box ausführt, sie lesen kann. Das ist Absicht: Es ist deine Box und deine Anmeldedaten. Einen Agenten zu konfigurieren ist ohnehin eine privilegierte Aktion, daher ist der Schalter pro Agent die einzige Stellschraube; es gibt keinen separaten Schalter auf Organisationsebene. ## Engines und Modelle **Claude Code**, **Cursor**, **OpenCode**, **Hermes Agent**, **Gemini CLI**, **Codex**, **Pi** und **OpenClaw** sind getrennte Einträge im Chat-Auswahlmenü (oder Agenten, die du mit entsprechend gesetztem `agentKind` konfigurierst). Für **gateway-verwaltetes Claude Code, OpenCode, Hermes Agent, Gemini CLI, Codex, Pi oder OpenClaw** kommt das Modell aus der Liste der unterstützten Modelle des Agenten im **Providers**-Katalog — wähle es im Modellauswahlmenü. Claude Code und OpenCode werden standardmäßig mit Claude Fable 5 ausgeliefert, und Fable-Kapazität ist rationiert: Markieren die Sicherheitsklassifikatoren eine Anfrage, ist das Modell überlastet oder das Fable-Kontingent erschöpft, schlägt der Zug nicht fehl — die Sitzung fällt automatisch auf das im Katalogeintrag hinterlegte Fallback-Modell zurück, Claude Opus 4.8 (nur Claude Code; OpenCode nutzt die von dir gewählte Gateway-Modell-ID). Hermes Agent, Pi und OpenClaw werden mit Claude Sonnet 4.6 und Claude Opus 4.8 ausgeliefert, Gemini CLI mit Gemini 3 Pro und Gemini 3 Flash, Codex mit GPT-5.5 und GPT-5.5 Pro; sie alle bestreiten die ganze Runde auf dem gewählten Modell — ein automatisches Fallback gibt es dort nicht. Eine OpenClaw-Besonderheit: Seine Laufzeit meldet sich headless erst am Ende der Runde, im Chat siehst du also die fertige Antwort und die Nutzung, keine Werkzeug-für-Werkzeug-Zeitleiste. Für **env-verwaltetes Cursor** (und BYO auf jeder Laufzeit) akzeptiert der **Modelle**-Editor unter Anweisungen **Runtime-IDs** aus deinem Konto — führe `agent models` in einer Sandbox-Sitzung aus, um zu sehen, was dein Abo freigibt. Lass die Liste leer, damit die Laufzeit ihr Standardmodell wählt (Auto). Das Chat-Modellauswahlmenü zeigt einen schreibgeschützten Indikator — den Kurznamen der konfigurierten ID oder **Standardmodell**, wenn die Liste leer ist — statt des Katalog-Dropdowns. Ein **BYO-Hermes-Agent** nutzt Anmeldedaten, die du unter [Umgebungsvariablen & Geheimnisse](/de/platform/member/environment) hinterlegst — je nach Provider üblicherweise `OPENROUTER_API_KEY`, `OPENAI_API_KEY` oder `ANTHROPIC_API_KEY`. Setze das Modell auf eine Hermes-/OpenRouter-übliche ID (zum Beispiel `openrouter:anthropic/claude-sonnet-4.6`). Ein **BYO-Gemini-CLI**-Agent nutzt deine eigenen Google-Anmeldedaten aus [Umgebungsvariablen & Geheimnisse](/de/platform/member/environment) — `GEMINI_API_KEY` für die Gemini-API oder `GOOGLE_API_KEY` mit `GOOGLE_GENAI_USE_VERTEXAI=true` für Vertex AI. Tippe rohe Google-Modell-IDs (zum Beispiel `gemini-3.1-pro-preview`); die mitgelieferten katalogförmigen Standardwerte werden zur Laufzeit in ihre Google-nativen IDs übersetzt. Ein **BYO-Pi**-Agent nutzt Anmeldedaten, die du unter [Umgebungsvariablen & Geheimnisse](/de/platform/member/environment) hinterlegst — je nach Provider üblicherweise `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY` oder `OPENAI_API_KEY`. Setze das Modell auf eine ID aus Pis eigenem Katalog (`pi --list-models` in einer Sandbox-Sitzung) — zum Beispiel `anthropic/claude-sonnet-4.6` mit einem OpenRouter-Schlüssel; die mitgelieferten katalogförmigen Standardwerte werden zur Laufzeit in diese OpenRouter-üblichen IDs übersetzt. Pi hat keine eingebauten Web-Tools; Fakten von außen kommen über die gebundenen Integrationen oder das, was `curl` auf der Netz-Erlaubnisliste der Sandbox erreicht. Ein **BYO-OpenClaw**-Agent nutzt Anmeldedaten, die du unter [Umgebungsvariablen & Geheimnisse](/de/platform/member/environment) hinterlegst — je nach Provider `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` oder `OPENROUTER_API_KEY`. Setze das Modell auf eine OpenClaw-übliche `provider/model`-Referenz (zum Beispiel `anthropic/claude-sonnet-4-6`) oder lass es leer für den Laufzeit-Standard. Ein **BYO-Codex**-Agent nutzt den `OPENAI_API_KEY`, den du unter [Umgebungsvariablen & Geheimnisse](/de/platform/member/environment) hinterlegst, und spricht direkt mit der OpenAI-API. Mitgelieferte Katalogverweise werden über die `nativeModelId` des Eintrags übersetzt (etwa `gpt-5.5`); selbst eingegebene IDs bleiben unverändert. Ein **BYO-Claude-Code**-Agent tippt rohe Anthropic-IDs — `claude-opus-4-20250514` etwa — in Prioritätsreihenfolge. Mitgelieferte Pack-Agenten mit katalogförmigen Verweisen werden zur Laufzeit über `nativeModelId` des Katalogeintrags übersetzt; selbst eingegebene IDs bleiben unverändert. ## Kosten und Budget Runden externer Agenten können lang sein und das Modell viele Male aufrufen, daher kosten sie mehr als eine einzelne Chat-Antwort. Jede verwaltete Runde läuft gegen ein Pro-Runde-Budget, und die [Richtlinien und Limits](/de/platform/admin/governance/policies-and-limits) der Organisation begrenzen die Ausgaben pro Nutzer, pro Team oder pro Agent. Die Nutzung wird wie bei jedem anderen Agenten in der [Nutzungsanalyse](/de/platform/admin/governance/usage-analytics) erfasst und dem externen Agenten zugeordnet, sodass du siehst, was diese Läufe kosten. Diese Abrechnung gilt nur für den **gateway-verwalteten** Pfad — also verwaltete Claude-Code-, OpenCode-, Hermes-Agent-, Gemini-CLI-, Codex-, Pi- und OpenClaw-Runden. Env-verwaltete und BYO-Agenten laufen auf Anmeldedaten außerhalb des Gateways: Ihre Runden fließen nicht in die Nutzungsanalyse ein und die Ausgabengrenzen der Organisation greifen nicht; Kosten und Ratenlimits liegen bei deinem Provider-Konto. ## Coding-Agenten auf dem Task-Board In den Einstellungen ist **Coding-Agent** das Produktlabel für Agenten, deren Chat in einer Sandbox-CLI (Claude Code oder Cursor) läuft, oder deren Task-Dispatch in JSON über **`runtime`** (tale-daemon auf deinem Rechner) oder **`preferDurableStepForTasks`** (durable Sandbox-Schritt) konfiguriert ist. Das Label allein ändert nicht, wie Board-Tasks laufen — der Dispatch folgt diesen JSON-Feldern, nicht der Chat-Sandbox. Wenn du einen Coding-Agenten einem Board-Task zuweist, hängt das Ergebnis von der Konfiguration ab: - **Agent** (Plattform-Tool-Schleife, keine Sandbox-CLI, kein Task-Runtime) — nutzt Plattform-Tools und postet Ergebnisse als Task-Kommentare. - **Coding-Agent + `runtime`** — Tasks laufen auf deinem Rechner (tale-daemon) in einem Git-Workspace. - **Coding-Agent + `preferDurableStepForTasks`** — Tasks laufen in einem Sandbox-Container; das Ergebnis ist eine Summary-Datei. - **Coding-Agent, nur Sandbox** (external-agent-Chat, ohne Runtime oder Durable-Flag) — Chat läuft in einer Sandbox; **Board-Tasks nutzen die Plattform-Schleife**, bis du einen Daemon bindest oder durable Tasks im Agent-JSON aktivierst. Der Assignee-Picker zeigt diese Hinweise beim Auswählen. Für Recherche, Texte oder persönliche Deliverables weise eine Person oder einen Plattform-**Agent** zu, nicht einen Coding-Agenten für Repo-Arbeit. ## Wo das hineinpasst Ein externer Agent verwandelt einen Chat-Thread in eine Live-Sitzung mit einem Coding-Werkzeug in einer Sandbox — du steuerst ihn in normaler Sprache, er arbeitet in einem isolierten Arbeitsbereich, und die Sitzung bleibt für Folgefragen bestehen, bis du den Thread schließt. Die Anmeldedaten sind die Achse, die entscheidet, wie viel davon unter der Kontrolle der Organisation läuft: Ein gateway-verwalteter Agent bleibt am Plattform-Gateway unter den Grenzen und der Erfassung der Organisation, während ein env-verwalteter oder BYO-Agent mit den Schlüsseln läuft, die du unter [Umgebungsvariablen & Geheimnisse](/de/platform/member/environment) hinterlegst, und deinem eigenen Provider-Konto gegenüber rechenschaftspflichtig ist. Die Drift-Kandidaten hier sind die Agenten- und Modellnamen; kombiniere diese Seite mit der laufenden [Provider-Liste](/de/platform/admin/providers), statt dir bestimmte Modellzeichenketten zu merken, und mit [Integrationen](/de/platform/integrations/overview) für die verbundenen Integrationen, die der Agent erreichen kann — von GitHub für einen echten Pull-Request-Workflow bis zu einer Such- oder Datenintegration, die externe Fakten in die Arbeit holt. Wenn Claude Code oder Codex statt in der verwalteten Sandbox auf eigener Hardware laufen sollen — für Board-Aufgaben statt Chat —, sieh dir [tale-daemon](/de/self-hosted/operate/tale-daemon) an. # Agent-Wissen Source: https://tale.dev/docs/de/platform/agents/knowledge Wissen ist das, was ein Agent zur Antwortzeit abrufen und zitieren kann. Ohne Wissen ist der Agent generisch; mit Wissen antwortet er aus deinen Dokumenten und zitiert, woher die Antwort kam. Der Tab **Wissen** des Agents steuert zwei Dinge: _wie_ der Agent abruft (der Abrufmodus) und _was_ im Scope liegt (welche Dokumente). <Frame caption="Der Wissen-Tab — oben der Abrufmodus, darunter die Dokument-Scopes und das, was jeder davon gerade hält."> ![Der Wissen-Tab des Agenten-Editors mit Tool als gewähltem der vier Abrufmodi, eingeschalteten Schaltern für Team- und Organisationsdokumente, einem Kasten für Team-Dokumente mit dem Hinweis, dass für dieses Team keine Dokumente gefunden wurden, und der Liste der Organisationsdokumente, in der jede Datei ein Abzeichen Indexiert trägt.](/images/platform/agent-editor-knowledge.webp) </Frame> ## Einen Abrufmodus wählen Vier Modi wägen Kosten gegen Abdeckung ab. **Tool** lässt den Agent bei Bedarf suchen — der Abruf läuft nur, wenn das Modell entscheidet, dass es ihn braucht. **Kontext** injiziert relevantes Wissen in jede Antwort, ob das Modell gefragt hätte oder nicht. **Beides** kombiniert beide, und **Aus** schaltet die Wissensdatenbank für diesen Agent komplett ab. Starte mit **Tool**; wechsle zu **Kontext**, wenn der ganze Job des Agents das Antworten aus den Dokumenten ist und du den Abruf bei jeder Antwort willst. ## Den Dokument-Scope setzen Die Wissensdatenbank durchsucht Dokumente, die in deine Organisation hochgeladen wurden — dieselbe Bibliothek, die du unter [Dokumente](/de/platform/knowledge/documents) verwaltest. Zwei Schalter setzen den Scope: **Team-Dokumente einbeziehen** deckt das zugewiesene Team des Agents ab, und **Organisationsdokumente einbeziehen** deckt Dokumente ab, die keinem Team zugewiesen sind. Der Tab listet, was jeder Scope gerade enthält, mit dem Indexzustand pro Dokument — nur Dokumente im Zustand **Indiziert** sind abrufbar. ## Dem Agent eigene Dokumente geben **Agent-Dokumente** sind Uploads, auf die nur dieser Agent zugreifen kann — klicke auf **Dokumente hochladen**, und die Dateien treten in den Abruf-Scope dieses Agents ein, ohne die geteilte Bibliothek zu betreten. Greif dazu, wenn die Quelle zum Job des Agents gehört statt zur Organisation: ein Triage-Playbook, eine produktspezifische FAQ. ## Wie der Abruf in der Antwort landet Wenn der Agent abruft, hängen sich Zitate an die Sätze, die sie stützen — Hovern zeigt die Quelle, Klicken öffnet sie. Alles Abrufbare konkurriert bei jeder Frage um Relevanz, also halte den Scope eng: ein breiter Scope macht den Abruf lauter, nicht klüger. ## Wann du danach greifst Strukturierte Datensätze und Live-Quellen sind Tools, kein Wissen — und Dateien für eine einzelne Konversation sind Anhänge. Die Grenzen: | Nutze… | Wenn der Agent braucht… | | ------------------------------------------------------- | ------------------------------------------------------------- | | Wissen (dieser Tab) | Hochgeladene Dokumente in jedem Chat durchsuchen und zitieren | | [Tools](/de/platform/agents/tools) | Kunden, Produkte, Lieferanten, Websites oder Live-Systeme | | [Anhänge](/de/platform/chat/attachments) | Eine Datei, die nur für einen Chat zählt | | [Projekt-Agenten](/de/platform/projects/project-agents) | Wissen, das auf ein Projekt begrenzt ist | ## Wo das hingehört Agent-Wissen ist die Antwort auf „dieser Agent soll aus diesen Dokumenten antworten“. Der breitere Abschnitt [Wissen](/de/platform/knowledge/overview) ist der Ort, an dem die Quellen liegen und indiziert werden; dieser Tab verdrahtet einen Agent mit einem Scope daraus. Für den Bau von Anfang bis Ende — hochladen, Scope setzen, fragen, Zitate prüfen — geh [Agent mit Wissen](/de/tutorials/editor/agent-with-knowledge) durch. # Agent-Versionen Source: https://tale.dev/docs/de/platform/agents/versions Jeder Speichervorgang eines Agents erzeugt einen Snapshot. Der Button **Verlauf** oben rechts im Agenten-Editor öffnet diese Snapshots in umgekehrt chronologischer Reihenfolge; Vergleichen zeigt, was sich geändert hat, und Wiederherstellen ersetzt den aktuellen Stand durch eine frühere Version. Es gibt keine Unterscheidung zwischen manuellem Speichern und Auto-Speichern — jede persistierte Änderung ist eine Version. Der Mechanismus ist klein, aber lasttragend. Die meisten Teams justieren die Anweisungen eines Agents wöchentlich; ohne den Verlauf würde das Team den Änderungen nie trauen. ## Eine Änderung prüfen Öffne den Agent und klicke auf **Verlauf**. Die Liste zeigt oben **Aktuelle Version** und darunter jede frühere **Snapshot-Version**, mit Autor und Zeitstempel pro Zeile. Wähle einen Snapshot, und **Änderungen vergleichen** stellt die Unterschiede zwischen ihm und der aktuellen Version gegenüber — die geänderten Felder heben sich hervor —, bevor du dich für das Wiederherstellen entscheidest. ## Eine Version wiederherstellen Klicke in einem Snapshot auf **Diese Version wiederherstellen**. Der aktuelle Stand des Agents wird durch den Snapshot ersetzt — eine Meldung bestätigt **Agent aus Verlauf wiederhergestellt** — und die Wiederherstellung landet als eigener Eintrag auf der Zeitleiste; Wiederherstellungen sind also additiv, nicht destruktiv. Chats, die schon gegen die vorherige Version laufen, laufen auf ihr weiter, bis sie enden; die wiederhergestellte Version gilt ab dem nächsten Chat. ## Was versioniert wird Die Versionierung deckt die Konfiguration des Agents ab: Anweisungen, die Modell-Liste, Tool-Auswahlen, Wissens-Einstellungen, Gesprächseinstiege und Metadaten. Sie deckt nicht die zugrunde liegenden Wissensquellen ab — ein ersetztes Dokument, aus dem der Agent abruft, ändert, was der Agent antwortet, ohne die Version des Agents zu erhöhen. Um eine Wissens-Änderung zu prüfen, siehe [Audit-Logs](/de/platform/admin/governance/audit-logs). ## Wo das hingehört Versionen sind das Sicherheitsnetz des Agents, aus demselben Grund, aus dem git das der Codebasis ist: alles Gespeicherte ist wiederherstellbar. Die Begleitseite ist [Audit-Logs](/de/platform/admin/governance/audit-logs) — sie deckt die organisationsweite Spur ab, wer was getan hat; der Verlauf deckt die Spur pro Agent ab, was es war. # Agent-Worker Source: https://tale.dev/docs/de/platform/agents/delegation Einen Worker startest du, wenn eine Aufgabe ihren eigenen fokussierten Kontext verdient: offene Recherche, Massen-Extraktion, ein langer Entwurf. Der Agent, mit dem du chattest, stellt bei Bedarf einen **Worker** zusammen — Name, Aufgabenanweisungen, optional eine Arbeitsmethode und eine Tool-Auswahl — lässt ihn laufen und faltet das Ergebnis in seine Antwort zurück. Worker sind flüchtig: Sie existieren für genau einen Job, und ihr Lauf erscheint als **Job-Karte** im Chat. Diese Seite gibt dir das Denkmodell, wann ein Worker die richtige Form ist und wie die Plattform ihn begrenzt hält. Der End-to-End-Durchlauf steht in [Arbeit an einen Worker geben](/tutorials/editor/delegate-between-agents). ## Wie ein Job läuft Ruft der Agent **spawn_agent** auf, löst Tale die Fähigkeiten des Workers auf, startet eine frische Kind-Konversation und lässt den Worker nicht-interaktiv laufen: Er sieht nur die Aufgabe, die der Agent geschickt hat (nicht den ganzen Chat-Verlauf), verfolgt seinen Fortschritt auf einer live sichtbaren Checkliste, und seine letzte Nachricht geht als Ergebnis an den Agenten zurück. Der Chat zeigt eine Job-Karte mit Name, Live-Fortschritt, Endstatus und einem aufklappbaren Protokoll von allem, was der Worker getan hat. Worker sprechen nie mit dir. Braucht ein Worker eine Eingabe, die nur ein Mensch geben kann, sagt er das in seinem Ergebnis, und der Agent fragt dich — Fragen kommen immer von dem Agenten, mit dem du tatsächlich sprichst. ## Fähigkeiten sind immer eine Teilmenge Ein Worker kann höchstens halten, was der startende Agent selbst hält. Drei Ebenen bestimmen die wirksame Auswahl: - **Org-Konfiguration** — die Tools, Skills und Integrationen des Agenten, wie von deinen Admins konfiguriert. Pro Worker gibt es nichts zu pflegen. - **Die Job-Auswahl** — der Agent wählt für diese Aufgabe die kleinste Menge aus seinen eigenen Fähigkeiten (weniger Tools = ein fokussierterer Worker). - **Plattform-Ausnahmen** — einige Tools wandern nie mit, allen voran das Nutzer-Frage-Tool: Die Fragen eines Workers laufen über den Agenten, damit eine Antwort nie ins Leere führt. Worker können auch keine Worker starten. Eine Ausnahme läuft in die Gegenrichtung: Die Dateien des Threads (Uploads, erzeugte Ergebnisse) kann jeder Worker immer auflisten und lesen — Dateien schreiben oder Code ausführen bleibt eine ausdrückliche Auswahl. Alles außerhalb dieser Grenzen wird still übersprungen und gemeldet — die Job-Karte zeigt, was weggeschnitten wurde, und der Agent passt sich an (sagt dir zum Beispiel, dass eine Integration verbunden werden muss). ## Arbeitsmethoden Für offene Aufgaben kann der Agent einen **Methodik-Skill** als Arbeitsmethode mitgeben — `web-research` ist eingebaut: Live-Planung auf der Checkliste, Suchbudgets pro Frage und ein zitiertes Ergebnis. Methodiken sind Skills; deine Admins steuern sie wie jeden anderen Skill. ## Zeitlimits und Budget Ein Worker läuft im verbleibenden Zug-Budget seines Agenten und kann es nicht verlängern; läuft die Zeit ab, endet der Job als `Zeit abgelaufen`, mit dem Teilfortschritt sichtbar auf der Karte. Token-Verbrauch rollt zum startenden Agenten hoch — Monatsbudgets pro Agent und Org-Budgetregeln sehen Job-Verbrauch als Verbrauch des Agenten. Admins begrenzen parallele Jobs pro Organisation über **Governance → agent_jobs** (Standard 10). ## Wann du danach greifst | Nimm … wenn | Worker | Einzelner Agent | Workflow | | -------------------------------------------------------- | ------ | --------------- | -------- | | Eine Teilaufgabe von einem isolierten Kontext profitiert | ✓ | | | | Der Agent inline gut antworten kann | | ✓ | | | Arbeit feste Stufen mit Freigaben dazwischen hat | | | ✓ | Die Kosten eines Workers sind ein zusätzlicher Lauf; der Gewinn ist ein sauberer Kontext mit genau den richtigen Fähigkeiten für die Teilaufgabe — und eine Job-Karte, die zeigt, was passiert ist. Sind die Stufen fest und willst du Freigaben oder Zeitpläne dazwischen, ist ein Workflow die richtige Form. # Agent-Tools Source: https://tale.dev/docs/de/platform/agents/tools Tools sind das, was ein Agent über das Erzeugen von Text hinaus tun kann. Das Modell entscheidet, welches Tool es aus der Liste aufruft, die der Autor des Agents gewährt hat; Tale führt das Tool aus, reicht das Ergebnis zurück, und das Modell macht weiter. Der Tab **Tools** des Agents ist diese Liste — ein durchsuchbarer Katalog mit Schaltern pro Tool, gruppiert in Kategorie-Karten. <Frame caption="Der Tool-Katalog — eine Karte pro Kategorie, jede mit der Zahl der Tools, die der Agent gewährt bekommen hat."> ![Der Tools-Tab des Agenten-Editors, gescrollt zu den Kategorie-Karten, mit Wissen bei drei von vier angehakten Tools und Dateien bei sieben von sieben, während Konversationen, Diskussionen, Analysen und Aufgaben & Projekte nichts gewährt bekommen haben.](/images/platform/agent-editor-tools.webp) </Frame> ## Tools einzeln gewähren Setz den Haken bei einem Tool, und der Agent kann es ab der nächsten Anfrage aufrufen; entfern den Haken, und der Agent vergisst, dass es existiert. **Tools durchsuchen…** filtert den Katalog nach Name oder Kategorie, jede Tool-Zeile trägt eine einzeilige Beschreibung dessen, was sie gewährt, und die Kopf-Checkbox einer Kategorie schaltet die ganze Gruppe auf einmal — der Zähler daneben zeigt, wie viele Tools der Gruppe an sind. Die Kategorien bilden die Oberflächen der Plattform ab: **Kunden**, **Produkte**, **Lieferanten** und **Websites** stellen Lese- und Update-Tools über strukturierte Datensätze bereit; **Konversationen** und **Diskussionen** lassen den Agent lesen und antworten; **Wissen** deckt Dokumentsuche und Schreiben ab; **Aufgaben & Projekte** enthält die eigene To-do-Liste des Agents; **Workflows** lässt ihn Workflows anlegen und ausführen; **Dateien** deckt die Dateioperationen des Agents ab; **System** hält **Code ausführen**, **Mensch fragen** und die übrigen Laufzeit-Tools. Gewähre die kleinste Menge, die den Job erledigt — jedes aktivierte Tool weitet, was der Agent in deinem Namen lesen oder ändern kann. **Code ausführen** in der Gruppe **System** ist das weitreichendste dieser Tools: Es führt Python, Node oder bash in der eigenen Sandbox des Chats aus und arbeitet dabei auf den Dateien, die der Chat schon hält, statt in einer leeren Box. Ein Aufruf führt einen Schnipsel direkt aus, führt ein Skript aus, das der Agent unter `/user/code/` abgelegt hat, oder installiert nur Pakete — deklarierte Pakete werden zuerst installiert und bleiben den Rest des Zugs erhalten, und was der Lauf unter `/user/output/` schreibt, erscheint als Datei im Chat. Dateien und Ordner, die du mit `@` anheftest, landen in dieser Sandbox unter `/user/uploads/`, sodass der Code die echten Bytes öffnet statt eines Retrieval-Schnipsels. <Note> Ein Agent startet für eine Teilaufgabe von sich aus einen fokussierten **Worker** — das ist kein Tool, das du hier umschaltest. [Agent-Worker](/de/platform/agents/delegation) deckt ab, wann das der richtige Zug ist und wie ein Worker eine begrenzte Teilmenge der Fähigkeiten des Agents erbt. </Note> ## Websuche konfigurieren **Websuche** ganz oben im Tab ist ein Modus, keine Checkbox: **Aus**, **Tool** (der Agent sucht bei Bedarf), **Kontext** (relevante Web-Ergebnisse werden in jede Antwort injiziert) oder **Beides**. Die Websuche durchsucht nur Inhalte von Websites, die deiner Organisation hinzugefügt wurden — sie ist kein offener Crawl; die Quellen verwaltest du unter [Websites](/de/platform/knowledge/crawling). ## Integrationen und Workflows binden Unter dem Katalog hängen **Gebundene Integrationen** und **Gebundene Workflows** bestimmte Integrationen oder Workflows als eigene Tools an, sodass der Agent sie aufrufen kann, ohne die Integration oder die Workflow-Id selbst zu benennen. Binde die, von denen der Job des Agents abhängt; verbundene [MCP-Server](/de/platform/integrations/mcp-servers) erreichen den Agent auf demselben Weg, über die Integrationen der Organisation. ## Wie Tool-Aufrufe erscheinen Tool-Aufrufe erscheinen im Chat als eingeklappte Karten zwischen der Nachricht des Users und der Antwort. Eine aufgeklappte Karte zeigt den Tool-Namen, die Eingaben, die das Modell ausgegeben hat, und das Ergebnis, das Tale zurückgab. Ein fehlgeschlagener Tool-Aufruf zeigt den Fehler; das Modell versucht es beim nächsten Zug meist mit anderer Form erneut. ## Wann du danach greifst | Nutze Tools, wenn… | Nutze Wissen, wenn… | | --------------------------------------------------------------- | -------------------------------------------------- | | Der Agent handeln muss — abfragen, ändern, ausführen, antworten | Der Agent abgerufene Dokumente zitieren muss | | Die Daten strukturierte Datensätze oder Live-Systeme sind | Die Daten hochgeladene oder gecrawlte Inhalte sind | ## Wo das hingehört Tools weiten, was ein Agent tun kann; sie weiten auch die Vertrauensgrenze, denn der Agent kann jetzt in deinem Namen lesen, schreiben oder aufrufen. Lies diese Seite zusammen mit der [Run-Code-Richtlinie](/de/platform/admin/governance/run-code-policy), wenn der Agent Code ausführen soll. Die Anweisungen des Agents bleiben der Ort der **Richtlinie**; der Tab **Tools** ist der Ort der **Oberfläche**. # Prompt-Bibliothek Source: https://tale.dev/docs/de/platform/workspace/prompt-library Die Prompt-Bibliothek ist die Oberfläche gespeicherter Prompts von Tale. Dort hältst du die Chat-Starter, nach denen du mehr als einmal greifst — einen Schreib-Stimmen-Prompt, den du für jeden Kunden-Mail-Entwurf wiederverwendest, einen Debugging-Prompt, den dein Team weiterreicht, einen Recherche-Prompt, auf den sich die ganze Organisation einigen sollte. Jede Rolle über Deaktiviert kann Prompts speichern und nutzen; der **Sichtbarkeits**-Hebel jedes Prompts entscheidet, wer ihn sonst sieht. Diese Seite ist die Referenz dafür, was ein Prompt ist, wie sich die drei Sichtbarkeits-Stufen verhalten, wie der Versionsverlauf funktioniert und wie Prompts in einen Chat gelangen. Die Bibliothek liegt unter **Prompts** in der Sidebar; dieselbe Bibliothek erscheint inline im Chat-Composer. <Frame caption="Die Prompt-Bibliothek über dem Chat-Composer — bereitgestellte Starter-Prompts mit den Sichtbarkeits-Tabs und Filtern, die die Liste eingrenzen."> ![Der Prompt-Bibliotheks-Dialog offen über dem Chat-Composer, listet bereitgestellte Starter-Prompts mit Sichtbarkeits-Tabs und einer Filterzeile darüber.](/images/platform/prompt-library-dialog.webp) </Frame> ## Was ein Prompt ist Ein Prompt ist ein gespeicherter Textbrocken — meist eine Frage oder eine Anweisung, die du sonst in den Composer tippen würdest — mit einem Titel und ein paar Metadaten-Feldern. Wenn du in Chat zu einem gespeicherten Prompt greifst, fügt Tale seinen Inhalt in den Composer; du kannst vor dem Senden bearbeiten, der Prompt ist keine verdeckte Systemnachricht. Jeder Prompt trägt: - Einen **Titel** (im Picker verwendet; automatisch aus dem Inhalt generiert, wenn du ihn leer lässt). - Den **Inhalt** (den eigentlichen Prompt-Text). - Eine **Sichtbarkeit** — `Persönlich`, `Team` oder `Global`. - Eine optionale **Team**-Bindung (wenn Sichtbarkeit `Team` ist). - Optionale **Tags** zum Filtern. Die Bibliothek ist nach Titel und Inhalt suchbar, nach Sichtbarkeit und Tag filterbar und nach Aktualität sortierbar. Der Inline-Picker des Composers ist dieselbe Bibliothek mit denselben Filtern. ## Die drei Sichtbarkeits-Stufen **Persönlich** ist nur für deine Augen. Ein persönlicher Prompt erscheint in deiner eigenen Bibliothek und nirgendwo sonst; niemand in der Organisation kann ihn sehen. Greif zu persönlich, wenn der Prompt auf deinen eigenen Workflow geformt ist und der Rest des Teams nicht profitieren würde. **Team** ist mit einem Team geteilt. Wähl das Team beim Speichern; jedes Mitglied dieses Teams sieht den Prompt in seiner Bibliothek. Greif zu Team, wenn der Prompt auf eine bestimmte Funktion geformt ist — der Antwort-Ton-Prompt des Support-Teams, der Bug-Triage-Prompt des Entwickler-Teams — und der Rest der Organisation nicht profitieren würde. **Global** ist organisationsweit. Jedes Mitglied der Organisation sieht den Prompt in seiner Bibliothek. Greif zu Global, wenn der Prompt eine Entscheidung kodiert, die die ganze Organisation gleich treffen sollte — die Schreibstimme, die die Marke erwartet, die Fragen-Vorlage, mit der jeder Recherchierende starten sollte. Sichtbarkeit ist beim Speichern setzbar und später bearbeitbar. Einen persönlichen Prompt zu Global hochzustufen ist ein Klick und löst keine Migration auf den Chats aus, die ihn schon nutzten — alte Chats behalten ihren eingefügten Inhalt, die neue Sichtbarkeit wirkt nur auf den Bibliotheks-Eintrag. ## Versionierung Einen Prompt über einen bestehenden Eintrag zu speichern, erzeugt eine neue Version. Der Versionsverlauf ist aus der Zeile des Prompts erreichbar; jede Version erfasst den Bearbeiter, den Zeitstempel und den Inhalts-Diff. Du kannst per Klick auf jede frühere Version zurückrollen. Der Versionsverlauf ist der Ort, an den man schaut, wenn ein Kollege einen globalen Prompt bearbeitet hat und der neue Inhalt für deinen Anwendungsfall nicht funktioniert. Rolle auf Bibliotheks-Ebene zurück, wenn alle zurück sollen; kopier die ältere Version in einen persönlichen Prompt, wenn nur du das alte Verhalten willst. ## Einen Prompt im Chat nutzen Der Chat-Composer hat unten einen Prompt-Picker. Öffne ihn, such oder filtere den gewünschten Prompt, und klick ihn an, um den Inhalt in den Composer zu fügen. Der Prompt ist jetzt deine Nachricht — bearbeite ihn, häng Dateien an, füg Kontext hinzu, sende. Einmal gesendet, verhält sich der Prompt wie jede Composer-Eingabe; Tale verfolgt nicht, welche Chats welche Prompts genutzt haben. Manche Prompts enthalten Template-Variablen — Platzhalter wie `{{customer_name}}` oder `{{topic}}`. Der Picker fragt dich vor dem Einfügen nach jeder Variable; der resultierende Inhalt ist der Prompt mit den befüllten Platzhaltern. Variablen werden im Inhalt des Prompts mit der `{{variable_name}}`-Syntax deklariert. ## Grenzen und Lebenszyklus Der Inhalt eines Prompts hat ein Größen-Limit — das Bibliotheks-Formular zeigt die aktuelle Auslastung gegen das Maximum, und die Speichern-Schaltfläche ist deaktiviert, wenn du es überschreitest. Das Limit ist großzügig genug, dass die meisten Prompts passen; wenn du anstößt, ist die richtige Antwort meist, dass der Prompt zwei Prompts ist. Einen Prompt zu löschen ist nur über den Versionsverlauf umkehrbar, wenn du ihn vorher mindestens einmal gespeichert hast. Persönliche Prompts werden bei Account-Löschung dauerhaft gelöscht; Team-Prompts überleben Team-Reorganisationen, außer das Team wird gelöscht; globale Prompts überleben alles außer einem expliziten Löschen. ## Wo das hingehört Die Prompt-Bibliothek ist die leichteste Form der Wiederverwendung in Tale — leichter als ein Agent (der Anweisungen, Wissen und Tools trägt), leichter als ein Skill (der Anweisungen und ein Skript verpackt). Greif zu einem Prompt, wenn die Wiederverwendung nur der Text ist; greif zu einem Agent, wenn die Wiederverwendung ein konfiguriertes Verhalten ist. Die natürliche nächste Lektüre ist [Starter und Prompts](/de/platform/chat/starters-and-prompts) dafür, wie Prompts im Chat-Composer neben den eigenen Startern eines Agents erscheinen. # Wissen Source: https://tale.dev/docs/de/platform/knowledge/overview Wissen ist der Bereich, in dem die Daten der Organisation liegen, damit Agenten sie lesen und zitieren können. Redakteure kuratieren sie einmal; Agenten rufen zur Antwortzeit darüber ab — deshalb kann ein Agent in Tale mit deiner Realität antworten statt mit den Trainingsdaten des Modells. Der Bereich öffnet auf sechs Tabs: **Dokumente**, **Wissenseinträge**, **Websites**, **Produkte**, **Kunden** und **Lieferanten**. <Frame caption="Der Dokumente-Tab — die meistgenutzte Ecke der Wissensdatenbank."> ![Der Dokumente-Tab des Wissensbereichs mit drei hochgeladenen Textdateien samt Spalten für Größe, Quelle, RAG-Status und Team.](/images/get-started/documents-list.webp) </Frame> ## Die zwei Formen Alles in diesem Bereich hat eine von zwei Formen. **Indexierte Inhalte** — die Dateien in Dokumente, die Fakten in Wissenseinträge, die Seiten, die ein Website-Crawl hereinholt — laufen durch die Indexierungs-Pipeline (extrahieren, chunken, einbetten, speichern), damit Agenten relevante Passagen abrufen und zitieren. **Typisierte Datensätze** — Produkte, Kunden, Lieferanten — sind Zeilen mit benannten Feldern, die Agenten als Daten lesen, nicht als Prosa: exakte Werte, kein Abruf-Rätselraten. Die Form, die du wählst, entscheidet, wie ein Agent den Inhalt nutzen kann — deshalb ist [Strukturierte Daten](/de/platform/knowledge/structured-data) eine Entscheidungsseite, nicht nur eine Referenz. ## Wie Agenten hineingreifen Ein Agent sieht die ganze Bibliothek nicht von selbst. Der Tab **Wissen** des Agenten steuert seinen Abruf-Umfang — welche Teile der Bibliothek er zur Antwortzeit durchsucht —, und team-gebundene Einträge bleiben für Agenten und Mitglieder außerhalb des Teams unsichtbar. Den Abruf treiben die RAG-getaggten Tools des Agenten, und jede abgerufene Passage trägt ihre Quelle, sodass Zitate auf die Datei, den Eintrag oder die Seite zurückzeigen, aus der sie kamen. Die Mechanik auf Agenten-Seite steht in [Agent-Wissen](/de/platform/agents/knowledge). ## Seiten in diesem Bereich <CardGroup cols="2"> <Card title="Dokumente" icon="file-text" href="/de/platform/knowledge/documents"> Dateien hochladen, die Indexierungs-Pipeline, unterstützte Formate und der Lebenszyklus pro Dokument. </Card> <Card title="Wissenseinträge" icon="book-open" href="/de/platform/knowledge/knowledge-entries"> Kleine Fakten mit Themen-Schlüssel — aus dem Chat mit Freigabe erfasst oder von Hand hinzugefügt. </Card> <Card title="Crawling" icon="globe" href="/de/platform/knowledge/crawling"> Aus einer öffentlichen Website wird Wissen — Domain, Scan-Intervall und die Ansicht der indexierten Seiten. </Card> <Card title="Strukturierte Daten" icon="table" href="/de/platform/knowledge/structured-data"> Kunden, Produkte, Lieferanten, Websites — wann ein typisierter Datensatz ein Dokument schlägt. </Card> </CardGroup> ## Wo das hingehört Wissen ist die Datenschicht, auf der jede verankerte Antwort steht; ohne sie wissen Agenten nur, was das Modell ohnehin weiß. Bring Inhalte über den Tab herein, der zu ihrer Form passt, und binde dann Agenten daran — die natürliche nächste Lektüre ist [Dokumente](/de/platform/knowledge/documents) für Dateien, [Strukturierte Daten](/de/platform/knowledge/structured-data) für Datensätze und [Agent-Wissen](/de/platform/agents/knowledge) für die Abrufseite. # Dokumente Source: https://tale.dev/docs/de/platform/knowledge/documents Der Dokumente-Tab ist die Dateifläche der Wissensdatenbank. Redakteure laden Dateien hoch, Tale schickt jede durch die Indexierungs-Pipeline — Text extrahieren, chunken, die Chunks einbetten, speichern —, und Agenten, deren Wissens-Umfang das Dokument abdeckt, rufen zur Antwortzeit relevante Passagen ab und zitieren sie. Diese Seite behandelt die Operator-Seite: Hochladen, die Status-Spalte, Team-Bindung, Ordner und den Lebenszyklus eines Dokuments. <Frame caption="Die Dokumente-Tabelle — Größe, Quelle, RAG-Status und Team-Bindung pro Datei."> ![Der Dokumente-Tab des Wissensbereichs mit drei hochgeladenen Textdateien samt Spalten für Größe, Quelle, RAG-Status und Team.](/images/get-started/documents-list.webp) </Frame> ## Hochladen Öffne **Wissen > Dokumente** und klicke auf **Dokumente hochladen** — das Menü bietet **Von deinem Gerät** und **Von Microsoft 365**. Das Upload-Tor akzeptiert die Formate, die den Großteil des Org-Wissens abdecken: PDF, Word (`.doc`, `.docx`), OpenDocument-Text (`.odt`), PowerPoint (`.ppt`, `.pptx`), Excel (`.xls`, `.xlsx`), CSV, reinen Text und Bilder (JPG, PNG, GIF, WEBP). Alles andere wird beim Upload abgewiesen. Hochladen und Indexieren sind zwei getrennte Tatsachen, und die Spalte **RAG-Status** verfolgt die zweite: **Wird indexiert**, während die Pipeline läuft, **Indexiert**, wenn Agenten den Inhalt abrufen können, **Fehlgeschlagen**, wenn die Pipeline auf einen Fehler lief, und **Neuindexierung nötig**, wenn die gespeicherten Chunks veraltet sind. Moderne Formate indexieren; das alte Office-Trio (`.doc`, `.xls`, `.ppt`) lädt hoch und bleibt herunterladbar, zeigt aber **Nicht indexiert** — Agenten kommen an den Inhalt erst heran, wenn du die Datei im modernen Format neu speicherst. ## Import aus Microsoft 365 **Von Microsoft 365** importiert aus OneDrive oder SharePoint statt von der Festplatte: wähle Dateien oder Ordner und entscheide dich für einen Import-Modus. **Einmaliger Import** holt die Dateien einmal — sie verhalten sich wie Uploads von der Festplatte. **Synchronisierungsimport** hält die Auswahl synchron: neue Dateien im OneDrive-Ordner erscheinen bei einem späteren Sync-Lauf, geänderte Dateien werden neu indexiert, und an der Quelle gelöschte Dateien verschwinden aus dem Workspace. Beide Modi erhalten die Ordnerstruktur deiner Auswahl. Die Synchronisierung deckt persönliche OneDrive-Ordner ab — eine SharePoint-Auswahl importiert immer einmalig. Um die Synchronisierung zu beenden — bei einem ganzen synchronisierten Ordner oder einer einzelnen synchronisierten Datei — öffne das Menü der Zeile und klicke auf **Synchronisierung beenden**; die importierten Dokumente bleiben im Workspace und werden nicht mehr aktualisiert. Auch das Löschen eines synchronisierten Ordners oder einer einzelnen Datei beendet die Synchronisierung. In allen Fällen bleiben die Dateien in OneDrive unberührt. ## Team-Bindung, Ordner, Quellen Jede Zeile trägt eine Zelle **Teams** — standardmäßig **Organisationsweit**, oder die Teams, die du über **Team zuweisen** im Zeilenmenü wählst. Ein team-gebundenes Dokument ist für Mitglieder und Agenten außerhalb des Teams unsichtbar; das ist der Zugriffshebel der Wissensdatenbank. Projekt-Dateien liegen ganz außerhalb dieses Modells: Der **Wissen**-Tab eines Projekts hält Dateien, die auf dieses eine Projekt begrenzt sind, und sie tauchen weder in dieser Bibliothek noch in ihrer Team-Bindung auf — siehe [Dateien verwalten](/de/platform/projects/manage-files). **Neuer Ordner** hält große Bibliotheken navigierbar, und Integrationen bringen ihre eigene Struktur mit: Dokumente aus einem OneDrive- oder SharePoint-Sync landen unter Sync-Ordnern und zeigen ihre Herkunft in der Spalte **Quelle**, was Zitate bis ins Quellsystem nachvollziehbar hält. <Warning> Das Löschen eines Ordners löscht jede Datei und jeden Unterordner darin endgültig. Das Löschen eines OneDrive-Sync-Ordners entfernt auch dessen Auto-Sync-Konfiguration und -Historie — nie aber die Dateien in OneDrive selbst. </Warning> ## Neu indexieren und löschen **Neu indexieren** (Zeilenmenü) lässt die Pipeline erneut über die gespeicherte Datei laufen — der richtige Zug nach einem Indexierungsfehler oder wenn ein Dokument **Neuindexierung nötig** zeigt. **Löschen** entfernt das Dokument und seine indexierten Chunks; die Bestätigung sagt es unumwunden — die Aktion lässt sich nicht rückgängig machen. Dieselbe Datei erneut hochzuladen bringt den Inhalt als frisches Dokument zurück. Ein Klick auf ein Dokument öffnet die Vorschau, mit einer Seitenleiste für Größe, Quelle, RAG-Status, Teams, hochladende Person und Änderungsdatum — der schnellste Weg zu prüfen, worauf ein Zitat wirklich zeigt. ## Dokumente gegenüber strukturierten Daten Dokumente sind die unstrukturierte Hälfte der Wissensdatenbank. Ist der Inhalt eine Liste gleichartiger Dinge mit denselben Feldern — Kunden, Produkte, Zulieferer —, dient ein typisierter Datensatz den Agenten besser als ein hochgeladenes Tabellenblatt: exakte Werte statt abgerufener Passagen. Die Entscheidungsregeln stehen in [Strukturierte Daten](/de/platform/knowledge/structured-data). ## Wo das hingehört Dokumente sind die meistgenutzte Ecke der Wissensdatenbank — die meisten Zitate in den meisten Antworten zeigen hierher. Die Abrufseite — wie der Wissens-Umfang eines Agenten entscheidet, was er durchsucht — ist [Agent-Wissen](/de/platform/agents/knowledge); die faktengroße Schwesterfläche sind die [Wissenseinträge](/de/platform/knowledge/knowledge-entries), die dieselbe Pipeline dokumentweise nutzen. # Crawling Source: https://tale.dev/docs/de/platform/knowledge/crawling Eine Website ist die Form der Wissensdatenbank für „eine öffentliche Seite, die der Agent kennen soll“. Du gibst Tale eine Domain und ein Scan-Intervall; der Crawler entdeckt URLs, holt Seiten, extrahiert den Hauptinhalt, chunked und bettet den Text ein und serviert die Chunks zur Antwortzeit genauso wie bei Dokumenten. Diese Seite geht durch, was du zwischen dem Hinzufügen einer Domain und den ersten Agenten-Zitaten ihrer Seiten siehst. <Frame caption="Eine Website hinzufügen — Domain plus Scan-Intervall ist das ganze Formular."> ![Der Dialog Website hinzufügen auf dem Websites-Tab, der nach einer Domain und einem Scan-Intervall fragt, das standardmäßig auf alle sechs Stunden steht.](/images/platform/websites-add-dialog.webp) </Frame> ## Eine Website hinzufügen Öffne **Wissen > Websites** und klicke auf **Website hinzufügen**. Der Dialog hat zwei Felder: **Domain** (zum Beispiel `example.com`) und **Scan-Intervall** — jede Stunde, alle 6 Stunden (der Standard), alle 12 Stunden, täglich, alle 5 Tage, alle 7 Tage oder alle 30 Tage. Tale normalisiert die Domain — `https://`, `www.` und Schrägstriche am Ende sind verkraftbar — und weist alles ab, was sich nicht als Hostname lesen lässt. Klicke auf **Speichern**; der Scheduler nimmt neue Websites beim nächsten Takt auf, der erste Scan startet also binnen Sekunden. <Note> Es gibt kein Auth-Feld und keine Include/Exclude-Pfadliste — der Crawler sieht exakt das, was ein anonymer Besucher sieht. Alles hinter einem Login gehört stattdessen in [Dokumente](/de/platform/knowledge/documents) oder eine [Integration](/de/platform/integrations/overview). </Note> ## Wie URLs entdeckt werden Der Crawler versucht zuerst den kooperativen Weg. Er löst die Startseite auf und geht jede Sitemap durch, die die Website veröffentlicht — `sitemap.xml`, Sitemap-Indizes, gezippte und in der robots-Datei deklarierte Sitemaps — und sammelt so die URL-Liste, die die Website selbst pflegt. Websites mit gesunder Sitemap bekommen vollständige Abdeckung ohne Raten. Fehlt die Sitemap, ist sie kaputt oder leer, fällt der Crawler auf einen Breitensuche-Linklauf von der Startseite zurück: nur Links innerhalb der Domain, externe und Social-Links fallen weg, Navigations- und Footer-Chrome wird vor der Extraktion entfernt. Der Fallback deckt Websites ohne Sitemap ab, erreicht aber nie die Vollständigkeit einer gepflegten Sitemap. ## Der Scan-Zeitplan Das Intervall entscheidet, wie oft URLs neu entdeckt und Seiten neu geholt werden. Jeder Scan ist inkrementell: Unveränderte Seiten werden übersprungen, geänderte neu extrahiert und neu eingebettet, neue Seiten kommen dazu, entfernte fliegen aus dem Index. Agenten, die auf die Website zeigen, sehen den neuen Inhalt beim nächsten Abruf — einen separaten Veröffentlichungsschritt gibt es nicht. ## Die Tabelle lesen Jede Zeile zeigt die Domain, ihren **Status** — **Inaktiv** zwischen Scans, **Wird gescannt** im Flug, **Aktiv** nach einem erfolgreichen Scan, **Fehler**, wenn der letzte Scan fehlschlug, **Lösche…** während der Entfernung —, den Prozentwert **Indexiert** (Hover zeigt gecrawlte von insgesamt gefundenen Seiten), die letzte **Gescannt**-Zeit und das **Intervall**. Öffne eine Zeile für den entdeckten Titel und die Beschreibung der Website; klicke auf **Seiten anzeigen** für die Seitenliste — jede indexierte URL mit Wortzahl, Chunk-Zahl und letzter Crawl-Zeit, plus ein Suchfeld, das über die indexierten Chunks läuft und damit der schnellste Weg ist zu prüfen, was ein Agent wirklich abrufen würde. ## Wo das hingehört Crawling ist der günstige Weg, eine öffentliche Website in den Agenten-Kontext zu holen: eine Domain, ein Takt, und der Rest ist das Problem des Crawlers. Der Preis ist die Grenze des anonymen Besuchers — private Inhalte brauchen [Dokumente](/de/platform/knowledge/documents) oder eine Integration. Wie die Website-Zeilen neben Kunden, Produkten und Lieferanten stehen, liest du in [Strukturierte Daten](/de/platform/knowledge/structured-data). # Wissenseinträge Source: https://tale.dev/docs/de/platform/knowledge/knowledge-entries Wissenseinträge sind die Faktenfläche der Wissensdatenbank. Wo ein Dokument eine ganze Datei trägt, trägt ein Eintrag einen kleinen, haltbaren Fakt — „Der Laden öffnet um 9“, „Das Rückgabefenster beträgt 3 Tage“ —, abgelegt unter einem Themennamen. Einträge fahren auf derselben Indexierungs-Pipeline wie Dokumente, jeder Agent mit passendem Umfang ruft sie also ab und zitiert sie wie jede andere Quelle; besonders macht sie, wie sie hereinkommen und wie Korrekturen ersetzen, was sie korrigieren. <Frame caption="Der Wissenseinträge-Tab — Thema, Inhalt, Quelle und Indexierungsstatus pro Fakt."> ![Der Wissenseinträge-Tab mit drei von Hand hinzugefügten Fakten, jeder mit dem Quellen-Tag Manuell und dem Status-Badge Indexiert.](/images/platform/knowledge-entries-list.webp) </Frame> ## Woher Einträge kommen **Aus dem Chat, mit deiner Freigabe.** Agenten mit aktiviertem Wissens-Schreib-Tool können vorschlagen, einen Fakt zu speichern, den du im Chat genannt oder korrigiert hast. Der Vorschlag erscheint als Karte im Chat — **In Wissensdatenbank speichern**, mit dem Thema und dem vollen Inhalt; existiert das Thema bereits, wird die Karte zu **Wissensdatenbank aktualisieren** und warnt, dass die Freigabe den bestehenden Eintrag ersetzt. Nichts landet, bevor du auf **Genehmigen** klickst; **Ablehnen** verwirft den Vorschlag. <Note> Das Tool ist standardmäßig aus — aktiviere es pro Agent in den Tool-Einstellungen des Agenten. Ein Agent kann nie in das geteilte Wissen der Org schreiben, ohne dass ein Mensch den exakten Text abgesegnet hat. </Note> **Von Hand.** Klicke unter **Wissen > Wissenseinträge** auf **Eintrag hinzufügen**. Gib ein **Thema** (bis zu 120 Zeichen — kurz und stabil, wie eine Überschrift) und den **Inhalt** als Markdown (bis zu 8000 Zeichen), so geschrieben, dass er ohne umgebendes Gespräch verständlich ist. Die Spalte **Quelle** hält die zwei Herkünfte auseinander: **Chat** oder **Manuell**. ## Eine aktive Version pro Thema Themen sind der Dedup-Schlüssel: Ein freigegebener Chat-Vorschlag für ein bestehendes Thema oder eine Bearbeitung ersetzt die aktive Version, statt eine zweite daneben zu stellen — die Wissensdatenbank serviert nie zwei Versionen desselben Fakts. Einen neuen Eintrag unter einem bestehenden Thema anzulegen wird mit einem Duplikat-Fehler abgewiesen; bearbeite stattdessen den bestehenden Eintrag. Ersetzte Versionen gehen nicht verloren. Öffne einen Eintrag für seine Details — Indexierungsstatus, letzte Aktualisierung und den **Versionsverlauf** mit jeder abgelösten Version und dem Zeitpunkt der Ablösung. Nur die aktive Version ist für den Abruf indexiert; der Verlauf existiert für Audit und Nachschlagen. ## Bearbeiten, Indexieren, Löschen Bearbeiten erzeugt eine neue aktive Version und indexiert im Hintergrund neu — das **Status**-Badge fällt kurz in die Indexierung und kehrt zu **Indexiert** zurück, sobald die Suche den neuen Text aufgenommen hat. Löschen entfernt den ganzen Eintrag: Die Bestätigung warnt, dass er auch aus der Wissensdatenbank verschwindet, Agenten ihn also nicht mehr finden, und dass sich die Aktion nicht rückgängig machen lässt. War der Fakt richtig, füge ihn neu hinzu. ## Wo das hingehört Wissenseinträge schließen die Schleife zwischen Gesprächen und der Wissensdatenbank: Eine einmal im Chat gemachte Korrektur wird ein Fakt, den jeder Agent abruft — ein Mensch gibt den exakten Wortlaut frei, und eine aktive Version pro Thema garantiert, dass der alte Fakt verschwindet, sobald der neue landet. Für die dateiförmige Hälfte lies [Dokumente](/de/platform/knowledge/documents); wie Agenten binden und abrufen, steht in [Agent-Wissen](/de/platform/agents/knowledge). # Strukturierte Daten Source: https://tale.dev/docs/de/platform/knowledge/structured-data Tales Wissensdatenbank führt zwei Formen nebeneinander. Dokumente sind Text, aus dem der Agent Chunks abruft; strukturierte Datensätze sind typisierte Zeilen, aus denen der Agent Felder liest. Die Form, die du wählst, ist die wichtigste Entscheidung dafür, wie ein Agent dein Wissen nutzt — liegst du falsch, verwässert der Agent entweder eine klare Antwort oder rät bei einem Wert, den du längst vorliegen hast. Diese Seite gibt dir das mentale Modell dafür, wann welche Form die richtige ist. Lies sie, bevor du einen Ordner voller Dateien lädst; komm zurück, wenn du versucht bist, eine Tabelle als PDF hochzuladen. ## Dokumente gegenüber strukturierten Datensätzen Ein Dokument ist frei geformt: Die Indexierungs-Pipeline extrahiert Text, chunked ihn, bettet die Chunks ein und serviert zur Antwortzeit Passagen über den Abruf. Der Agent sieht Passagen und zitiert sie nach Quelle. Das ist die richtige Form, wenn der Inhalt Prosa ist — Verträge, Handbücher, Wissensdatenbank-Artikel, Meeting-Notizen. Ein strukturierter Datensatz ist typisiert: Die Entität hat bekannte Felder (ein Kunde hat einen Namen, eine E-Mail, eine Branche; ein Produkt hat eine SKU, einen Preis, einen Bestand). Der Agent liest die Felder direkt, verknüpft über Entitäten hinweg und antwortet mit dem Wert. Das ist die richtige Form, wenn die Quelle eine Datenbankzeile ist — Konten, Bestellungen, Teile, Lieferantendaten. ## Die vier eingebauten Entitäten Vier strukturierte Tabs sitzen im Wissensbereich neben **Dokumente** und **Wissenseinträge**: - **Kunden** — die Menschen und Organisationen, mit denen du Geschäfte machst. - **Produkte** — die Dinge, die du verkaufst. - **Lieferanten** — die Zulieferer, bei denen du einkaufst. - **Websites** — öffentliche Seiten, die ein Crawler nach Zeitplan holt; der Datensatz hält Domain und Scan-Einstellungen, die indexierten Seiten halten den Inhalt ([Crawling](/de/platform/knowledge/crawling)). Strukturierte Datensätze teilen die Team-Bindungshebel der Wissensdatenbank: Ein team-gebundener Datensatz ist außerhalb des Teams genauso unsichtbar wie ein team-gebundenes Dokument. ## Content-Modelle für eigene Formen Wenn die vier eingebauten Entitäten nicht passen, definierst du mit Content-Modellen einen eigenen strukturierten Datensatztyp: die Entität benennen, ihre Felder deklarieren, Zugriff pro Feld setzen — und der neue Typ erscheint neben den eingebauten. Die Definitionen liegen bei den [Content-Modellen](/de/platform/admin/governance/content-models) der Governance. <Note> Content-Modelle kosten Governance-Aufmerksamkeit — Zugriff und Aufbewahrung jedes Feldes liegen bei dir. Greif dazu, wenn die Daten wirklich eine neue Form sind, nicht eine leichte Variante einer der vier eingebauten. </Note> ## Alles zusammen — ein CRM-Agent Ein CRM-Agent, der „Wo stehen wir mit Acme?“ beantwortet, nutzt beide Formen. Die Entität Kunden hält den kanonischen Datensatz — Name, Hauptkontakt, Branche, Status. Dokumente halten die Gesprächsnotizen und Verträge. Der Agent liest die Felder des Kunden direkt, ruft Passagen aus den Dokumenten ab und antwortet mit beidem: dem strukturierten Status aus Kunden, dem jüngsten Kontext aus der letzten Gesprächsnotiz. Ohne strukturierte Datensätze muss der Agent Acme namentlich über PDFs hinweg suchen und riskiert, zwei ähnlich benannte Kunden zu verwechseln. Ohne Dokumente kennt der Agent Acmes Status, kann dir aber nicht sagen, was im Gespräch am Dienstag passiert ist. ## Wann du wozu greifst | Nimm … wenn | Dokumente | Strukturierter Datensatz | | ------------------------------------------------------------------ | --------- | ------------------------ | | Die Quelle ist freie Prosa | ✓ | | | Die Quelle hat typisierte Felder und du willst exakte Werte zurück | | ✓ | | Du musst über viele Datensätze hinweg verknüpfen | | ✓ | | Der Agent soll Passagen nach Fundstelle zitieren | ✓ | | ## Wo das hingehört Strukturierte Daten sind die Naht zwischen deinen operativen Daten und der Agenten-Fläche. Nimm die vier eingebauten Entitäten für das, was sie abdecken; greif zu [Content-Modellen](/de/platform/admin/governance/content-models), wenn eine fünfte Form auftaucht. Die nächste Lektüre, die sich lohnt, ist [Dokumente](/de/platform/knowledge/documents) — die Indexierungs-Pipeline, die die unstrukturierte Hälfte bedient. # Genehmigungskonzepte Source: https://tale.dev/docs/de/platform/approvals/concepts Eine Genehmigung ist die Naht zwischen der Initiative eines Agents und deinem Urteil: eine Karte, die im Chat dort erscheint, wo die Aktion versucht wurde, und die Aktion anhält, bis ein Mensch entscheidet. Agents schlagen vor — einen Dokument-Schreibzugriff, einen ausgehenden API-Aufruf, einen Workflow-Lauf — und nichts läuft, solange die Karte aussteht. Der Chat-Composer sagt es ausdrücklich: **Beantworte die ausstehende Anfrage oben, um fortzufahren**. Diese Seite ist das Denkmodell — was eine Genehmigung auslöst, was die Karte bietet und was eine Entscheidung hinterlässt. Die Workflow-spezifischen Tore stehen auf [Genehmigungen in Workflows](/de/platform/automations/approvals-in-workflows); wo die Anforderungen deklariert werden, steht auf [Genehmigungen konfigurieren](/de/platform/approvals/configure). ## Was eine Genehmigung auslöst Jede Karte stammt von einem Agent, der auf etwas wirken will, das das Gespräch überdauert: - **Pläne** — ein Agent schlägt einen mehrstufigen Plan als Karte **Vorgeschlagener Plan** vor; **Genehmigen & ausführen** startet ihn. - **Dokument-Schreibzugriffe** — eine Karte **In Dokumenten speichern** hält Dateien, die ein Agent ablegen will; nichts landet im Dokumenten-Hub, bevor du genehmigst. - **Wissens-Schreibzugriffe** — eine Karte **In Wissensdatenbank speichern** hält einen Fakt, den ein Agent organisationsweit festhalten will. - **Integrationsaufrufe** — eine Operation mit Genehmigungspflicht (typischerweise ausgehende Schreibzugriffe) hält an, mit den exakten Parametern sichtbar. - **MCP-Tools** — ein Tool, das der Server mit **Genehmigung erforderlich** markiert, fragt, bevor es läuft. - **Workflow-Erstellung, -Aktualisierungen und -Läufe** — die Tore auf der Workflow-Seite, behandelt in [Genehmigungen in Workflows](/de/platform/automations/approvals-in-workflows). ## Die Entscheidungen auf einer Karte Jede Karte trägt den exakten Payload der Aktion — die Datei, den Fakt, die Parameter — und zwei Entscheidungen: genehmigen (der Button benennt die Aktion, etwa **Workflow ausführen** oder **Genehmigen & ausführen**) oder ablehnen. Integrationskarten fügen einen dritten Weg hinzu, **Änderungen vorschlagen**: Beschreib in freiem Text, was falsch ist, und der Agent überarbeitet den Aufruf, statt ihn aufzugeben. <Note> Genehmigungen werden in dem Gespräch entschieden, das sie unterbrechen — von der Person, die diesen Chat führt. Es gibt keinen separaten Genehmigungs-Posteingang und kein Routing an einen Genehmiger-Pool; die Person, für die der Agent arbeitet, ist die Person, die entscheidet. </Note> ## Zustände und die Spur Eine Karte wandert von **Ausstehend** über **Wird ausgeführt** zu **Abgeschlossen** — oder **Abgelehnt** — und behält ihren entschiedenen Zustand im Transkript, sodass sich ein Chat als Protokoll dessen wiederliest, was erlaubt wurde. Jede Entscheidung landet außerdem im [Audit-Log](/de/platform/admin/governance/audit-logs) mit Akteur, Aktion und Zeitstempel. Entschiedene Karten lassen sich nicht wieder öffnen; ein neuer Versuch heißt ein frischer Vorschlag und eine frische Karte. ## Wo das hingehört Genehmigungen sind das, was dich Agents echte Fähigkeiten anvertrauen lässt — Dateien, APIs, Workflows — ohne das Protokoll aus der Hand zu geben, wer was erlaubt hat. Lies als Nächstes [Genehmigungen konfigurieren](/de/platform/approvals/configure), um zu sehen, wo eine Anforderung eingeschaltet wird, und [Genehmigungen in Workflows](/de/platform/automations/approvals-in-workflows) für die Tore rund um Workflows. # Genehmigungen konfigurieren Source: https://tale.dev/docs/de/platform/approvals/configure Genehmigungspflichten sind in Tale deklarativ: Jede Fähigkeit trägt ihr eigenes Flag, das sagt, ob ein Agent zuerst fragen muss, und das Flag reist mit der Integration oder dem Server, der die Fähigkeit bereitstellt. Es gibt keine zentrale Regeltabelle zu pflegen — diese Seite zeigt, wo jedes Flag lebt und wie du abliest, was vor dem Ausführen fragen wird. Das Modell, was eine Genehmigungskarte ist und wer sie entscheidet, steht auf [Genehmigungskonzepte](/de/platform/approvals/concepts). Was folgt, ist die Konfigurationsoberfläche, Fähigkeit für Fähigkeit. ## Integrations-Operationen Jede Integration deklariert ihre Operationen, und jede Operation trägt ihr eigenes Genehmigungs-Flag. Öffne **Einstellungen > Integrationen**, klicke auf eine Integration, und ihre Operationsliste kennzeichnet die als **Genehmigung erforderlich** markierten — bei den mitgelieferten Konnektoren ist das die Schreibseite: Mail senden, Nachrichten posten, Issues erstellen. Lesezugriffe laufen ohne Karte; markierte Schreibzugriffe halten im Chat mit ihren exakten Parametern, bis jemand genehmigt. Bei einer eigenen Integration ist das Flag `requiresApproval` pro Operation in der `config.json`, die du mit **Integration hinzufügen** paketierst — entscheide beim Schreiben des Konnektors, welche seiner Operationen folgenreich genug sind, um zu fragen. <Frame caption="Der Integrationskatalog — die Detailansicht jedes Eintrags listet seine Operationen und welche davon eine Genehmigung verlangen."> ![Die Seite Einstellungen Integrationen auf dem Tab Alle Integrationen mit einem Kartenraster aus zwölf verbindbaren Diensten wie GitHub, Slack und Gmail.](/images/platform/integrations-catalog.webp) </Frame> ## MCP-Tools Das Manifest eines MCP-Servers markiert, welche seiner Tools ein Einverständnis brauchen. Öffne **Einstellungen > API > MCP**, klappe einen Server aus, und seine Liste **Erkannte Tools** kennzeichnet jedes markierte Tool mit **Genehmigung erforderlich** — diese fragen im Chat bei jedem Aufruf durch einen Agent. Das Flag stammt vom Autor des Servers; einen Server zu verbinden heißt, seinen Tool-Vertrag anzunehmen — lies die Liste also, bevor du einen aktivierst. [MCP-Server](/de/platform/integrations/mcp-servers) behandelt die Registrierung. ## Eingebaute Schreib-Tore Einige Tore sind ab Werk an und nicht konfigurierbar, weil die Aktion ihrer Natur nach folgenreich ist: - **Dokument-Schreibzugriffe** — ein Agent, der Dateien im Dokumenten-Hub ablegt, fragt immer (**In Dokumenten speichern**). - **Wissens-Schreibzugriffe** — ein Agent, der einen organisationsweiten Fakt speichert, fragt immer (**In Wissensdatenbank speichern**). - **Workflow-Erstellung, -Aktualisierungen und -Läufe** — ein Agent, der einen Workflow baut, bearbeitet oder startet, fragt immer; siehe [Genehmigungen in Workflows](/de/platform/automations/approvals-in-workflows). <Note> Der Hebel dafür ist nicht das Genehmigungs-Flag, sondern die Fähigkeit selbst: Ein Agent ohne Dokument- oder Workflow-Tools produziert die Karte gar nicht erst. Beschneide das [Tool-Set](/de/platform/agents/tools) des Agents, um die Fähigkeit ganz zu entfernen. </Note> ## Prüfen, was fragen wird Bevor du einen Agent vor echte Systeme stellst, lies seine Fähigkeiten wie ein Genehmiger: die Operationsliste der Integration auf markierte Schreibzugriffe, die **Erkannte Tools** des MCP-Servers auf markierte Tools und den Tool-Tab des Agents darauf, ob er überhaupt Schreib-Tools hält. Das [Audit-Log](/de/platform/admin/governance/audit-logs) protokolliert anschließend jede Entscheidung, die dieses Setup produziert. ## Wo das hingehört Konfiguration ist hier Verteilung — die Flags leben bei den Integrationen und Servern, denen die Fähigkeiten gehören. Lies [Genehmigungskonzepte](/de/platform/approvals/concepts) für den Kartenlebenszyklus, den diese Flags produzieren, und [Agent-Tools](/de/platform/agents/tools) für die Fähigkeitsseite derselben Grenze. # Tiefenrecherche Source: https://tale.dev/docs/de/platform/chat/deep-research Die Tiefenrecherche ist ein Composer-Modus, der eine Frage an einen spezialisierten **Rechercheur**-Agent übergibt. Der Agent plant die Arbeit als Liste von Unterfragen, sucht mit Tavily im offenen Web, liest die vielversprechendsten Seiten, verfolgt den Fortschritt in einer To-do-Karte, die du live mitlesen kannst, und schließt mit einem PDF-Bericht ab, der jede genutzte Quelle zitiert. Greif danach, wenn die Frage offen ist, die Antwort Belege braucht und du sonst eine Stunde mit zwanzig Browser-Tabs verbringen würdest. Diese Seite deckt die Tiefenrecherche-Oberfläche von Anfang bis Ende ab — wann du sie wählst, wie der Ablauf aussieht, das Budget, das sie davor bewahrt, ewig zu laufen, und woher die zitierten Quellen kommen. Die Mechanik des Agents hat dieselbe Form wie jeder andere Tale-Agent (siehe [Agent-Konzepte](/de/platform/agents/concepts)); ungewöhnlich sind hier der Live-To-do-Plan und die Tavily-Integration, die die Suchen antreibt. ## Wann du danach greifst Die Tiefenrecherche schlägt einen gewöhnlichen Chat bei Fragen, deren Wert nicht das bestehende Wissen des Modells ist, sondern das Zusammentragen aktueller, belegter Information. Drei Signale, dass es der richtige Modus ist: - Die Frage ist offen („was ist der aktuelle Konsens zu…", „vergleiche die drei führenden…"). - Du willst Zitate — ein Zitat ohne URL ist eine Vermutung. - Du nimmst zwei bis zehn Minuten Wartezeit für einen geschriebenen Bericht statt einer Chat-Antwort in Kauf. Für schmale Faktenfragen („was ist die Hauptstadt des Senegal") ist ein gewöhnlicher Chat schneller und genauso korrekt. Für Fragen zu deinen eigenen Daten („was hat der Kunde letzten Dienstag im Call gesagt") ist ein Agent mit [Wissens](/de/platform/agents/knowledge)-Bindungen die richtige Form — die Tiefenrecherche liest nur das offene Web, nicht deine Wissensdatenbank. ## Tiefenrecherche öffnen Öffne das Plus-Menü des Composers — Modi wohnen unter der Überschrift **Modi**, und **Deep research** erscheint dort, sobald der Rechercheur-Agent verfügbar ist. Wähl den Eintrag, und der Composer wechselt in den Rechercheur-Agent. Tipp die Frage und sende. Die Antwortansicht wechselt vom üblichen Streaming-Text zu einer **Recherche-Plan**-Karte mit drei bis sieben To-do-Einträgen, die der Agent als Unterfragen gewählt hat. <Frame caption="Modi wohnen im Plus-Menü des Composers; Einträge erscheinen, sobald ihre Voraussetzungen erfüllt sind."> ![Das geöffnete Plus-Menü des Composers zeigt den Eintrag Fotos & Dateien hinzufügen und einen Modi-Abschnitt mit dem Arena-Modus.](/images/platform/chat-composer-menu.webp) </Frame> Der Modus ist verfügbar, sobald ein Redakteur oder höher die **Tavily**-Integration unter [Einstellungen > Integrationen](/de/platform/integrations/overview) verbunden hat; ohne Tavily nennt der Menüeintrag die fehlende Integration, und ein Klick darauf öffnet die Integrationseinstellungen. ## Der Recherche-Plan Der Plan ist eine Liste von `pending`-To-do-Einträgen, die der Agent aus deiner Frage erzeugt hat. Bei komplexen Fragen pausiert der Agent nach dem ersten Plan und bittet dich um Bestätigung — eine Karte mit einem Ja/Nein-Feld erscheint, etwa **Mit diesem Plan fortfahren?** in deiner Sprache. Klick Ja, um zu starten; klick Nein, und der Agent läuft nicht weiter. Triviale Fragen überspringen die Bestätigung. Sobald er läuft, arbeitet der Agent die To-dos einzeln ab: 1. Setzt das aktuelle To-do auf `in_progress`. 2. Sucht bis zu dreimal über Tavily zu diesem To-do. 3. Liest bis zu zwei der vielversprechendsten URLs vollständig über Tavilys Extract-Operation. 4. Setzt das To-do auf `done` mit einer Erkenntnis in einem Satz. Die Karte aktualisiert sich live, sobald jeder Schritt landet. Du kannst zusehen, wie das Modell seine Argumentation formt; taucht mitten im Lauf eine neue Unterfrage auf, fügt der Agent sie der Liste hinzu. ## Suchen und Extraktionen Tavily ist der Open-Web-Suchanbieter hinter der Tiefenrecherche — die API ist für LLM-Agents optimiert und liefert Suchtreffer mit bereinigten Snippets und Scores pro Resultat. Zwei Operationen zählen: - **search** — Anfrage in natürlicher Sprache mit Tiefe (`basic` oder `advanced`), Topic (`general` oder `news`, mit einem `days`-Fenster für Aktualität) und einer optionalen Domain-Allowlist oder -Blocklist. - **extract** — holt den bereinigten Hauptartikel-Text für eine bis fünf URLs. Der Agent ruft das pro To-do auf den zwei besten Treffern auf, wenn ein Snippet nicht reicht. Tavilys Free Tier sind 1000 Aufrufe pro Monat; Paid Plans schalten die `advanced`-Tiefe bei der Suche und die Extract-Operation frei. Die Einrichtungsschritte stehen auf der Setup-Karte der Integration unter **Einstellungen > Integrationen**. ## Pro-Lauf-Budget Die Tiefenrecherche deckelt einen Lauf bei: - **3 Suchen + 2 Extraktionen pro To-do.** Der Integrations-Wrapper lehnt Aufrufe darüber hinaus ab. - **40 Argumentationsschritten insgesamt** über den ganzen Lauf. - **25 Minuten Wall-Clock.** Danach hört der Agent auf und synthetisiert mit dem, was er hat. - **60 Integrationsaufrufen insgesamt pro Lauf** als harter Obergrenze. Eine dieser Grenzen zu treffen stoppt die Suchphase und schiebt den Agent in die Synthese. Brauchst du mehr, lauf die Frage erneut mit engerem Umfang oder zerleg sie in zwei Fragen. ## Der PDF-Bericht Sobald jedes To-do `done` ist (oder abgebrochen, oder das Budget gegen eine Wand gelaufen ist), ruft der Agent das **pdf**-Tool einmal auf, um einen einzelnen strukturierten Bericht zu erzeugen: - **Conclusion** — ein bis drei Sätze, die die Frage direkt beantworten. - **Key points** — drei bis sieben Punkte, jeder mit mindestens einem Inline-Zitat zu einer Tavily-Quelle. - **Details** — die längere Analyse, nach Unterfrage gruppiert. - **Sources** — eine deduplizierte Liste jeder zitierten URL. Das PDF kommt als Anhangskarte im Chat an. Der Agent fügt den Bericht nicht in den Nachrichtentext ein — die Karte ist das Liefer-Ergebnis. Eine kurze Bestätigungszeile in deiner Sprache („Recherche abgeschlossen — den vollständigen Bericht findest du im angehängten PDF.") zeigt auf die Karte. Für chinesische, japanische und koreanische Berichte ist der Schriftsatz des PDF-Renderers unvollständig; in dem Fall gibt der Agent denselben strukturierten Bericht direkt im Chat aus und merkt an, dass ein ins Englische übersetztes PDF auf Anfrage verfügbar ist. ## Fehlerfälle - **Tavily nicht verbunden.** Der Agent gibt eine Einzeiler-Bitte an einen Redakteur aus, Tavily unter **Einstellungen > Integrationen** zu verbinden, und stoppt. - **Tavily-Kontingent ausgeschöpft.** Die Integration gibt `INTEGRATION_BUDGET_EXHAUSTED` zurück, und der Agent geht mit dem, was er hat, zur Synthese über. Der Free Tier trifft das etwa beim tausendsten Aufruf des Monats. - **Eine bestimmte URL scheitert beim Extrahieren.** Das betroffene To-do wird mit einem Grund als `failed` markiert; andere To-dos laufen weiter. - **Dein Budget reicht nicht.** Der Lauf stoppt, und der Agent synthetisiert. Die Karte zeigt, welche To-dos übersprungen wurden. ## Wo das hineinpasst Die Tiefenrecherche ist das schwerste Ende des Chat-Composers — sie erledigt in zehn Minuten, was ein Analyst in einem Nachmittag schaffen würde. Lies diese Seite zusammen mit [Agent-Konzepten](/de/platform/agents/concepts) (das Vier-Knöpfe-Modell, auf dem der Rechercheur-Agent gebaut ist) und der [Integrationen-Übersicht](/de/platform/integrations/overview) (wo Tavily neben den anderen Integrationen sitzt, die der Werkzeuggürtel eines Agents erreichen kann). Willst du deinen eigenen recherche-artigen Agent bauen, statt den mitgelieferten zu nutzen, führt dich [Einen Agent erstellen](/de/platform/agents/create) durch den Agent-Bau von Anfang bis Ende. # Geteilte Chats Source: https://tale.dev/docs/de/platform/chat/shared-threads Einen Chat zu teilen erzeugt einen Link, den jeder in deiner Organisation öffnen kann. Betrachter sehen das volle Transkript im Lesemodus; antworten können sie nicht, aber sie können den Chat in einen eigenen forken und von dort weitermachen. Der Mechanismus ist leicht genug für den beiläufigen Einsatz — teil eine Frage und ihre Antwort so, wie du ein Dokument teilen würdest. Diese Seite deckt die Teilen-Oberfläche von Anfang bis Ende ab: Teilen aktivieren, für wen der Link funktioniert, die Lesemodus-Ansicht und die Fork-Geste, die „ich möchte daran anknüpfen" in einen neuen Chat verwandelt. ## Einen Chat teilen Klick **Teilen** in der Kopfzeile des Chats. Der Dialog **Chat teilen** bietet **Teilen aktivieren** als Schalter und, einmal aktiviert, den Freigabelink mit **Link kopieren** und **Vorschau** — Letztere öffnet die Lesemodus-Ansicht, die Empfänger sehen werden. Füg den Link in den Kanal ein, den dein Team nutzt. <Frame caption="Der Dialog Chat teilen — org-weiter Link, Kopieren und Vorschau."> ![Der Dialog Chat teilen liegt über einem Chat und zeigt den eingeschalteten Schalter Teilen aktivieren, den Freigabelink sowie die Knöpfe Link kopieren und Vorschau.](/images/platform/chat-share-dialog.webp) </Frame> **Jeder in deiner Organisation mit dem Link kann diesen Chat sehen** — der Link ist auf die Org begrenzt, nicht auf das offene Internet. Teilen später zu deaktivieren macht den Link ungültig; Besucher landen auf einer Nicht-gefunden-Seite. ## Was Betrachter sehen Betrachter öffnen den Link und landen auf dem Chat mit einem Banner: **Du siehst einen geteilten Chat im Lesemodus**. Das Transkript liest sich genau so wie für den Autor, inklusive Tool-Aufrufen und Zitaten. Der Composer ist durch einen einzigen Hinweis ersetzt — **Das Senden einer Nachricht erstellt deine eigene Kopie dieses Chats** — und das ist der einzige Weg nach vorn. ## Einen geteilten Chat forken Die einzige Schreibaktion auf einem geteilten Chat ist **Diesen Chat forken**. Der Fork erzeugt einen neuen Chat im Besitz des Betrachters, mit dem vollen Transkript als Kontext kopiert. Das Original bleibt unverändert; der Fork hat keine Rückverbindung zum Original außer den Nachrichten, die er erbt. Aus Sicht des Betrachters ist der Fork nun ein gewöhnlicher Chat — Agent-Wahl, Modell-Wahl und Tools verhalten sich wie in jedem Chat, den er selbst gestartet hat. ## Wenn der Link veraltet Teilen zu deaktivieren macht den Link ungültig. Den Quellchat zu löschen schickt ihn in den [Papierkorb](/de/platform/admin/governance/trash), und der Link bricht; den Chat aus dem Papierkorb wiederherzustellen stellt den Link nicht wieder her — der Autor aktiviert das Teilen erneut, falls es wieder gebraucht wird. Bestehende Forks sind von beidem unberührt, weil sie eigenständige Chats sind. ## Wo das hineinpasst Geteilte Chats sind der leichtgewichtige Weg, jemandem im Team einen Chat zu übergeben, ohne das Produkt zu verlassen. Die schwergewichtige Alternative ist, die Person in ein [Projekt](/de/platform/projects/overview) zu holen, wo Chats, Dateien und Agents standardmäßig geteilt sind. Teilen ist für einmalige Übergaben; ein Projekt ist für laufende Zusammenarbeit an derselben Arbeit. # Chat Source: https://tale.dev/docs/de/platform/chat/overview Chat ist der tägliche Einstiegspunkt zu Tale. Du öffnest ihn, wählst einen Agent (oder keinen), tippst, und eine Antwort streamt zurück — mit Zitaten, Tool-Aufrufen und allem. Die meisten User verbringen hier mehr Zeit als in jedem anderen Tab; alles andere in Platform existiert, um Chat etwas Nützliches zu füttern oder zu regeln, was er tut. <Frame caption="Ein Chat mit einer gestreamten Antwort — die Oberfläche, der jedes andere Feature dient."> ![Ein Chat-Thread zeigt eine Nutzerfrage zu Onboarding-Feedback und eine Assistenten-Antwort mit einer Markdown-Tabelle aus drei Themen.](/images/platform/chat-thread-reply.webp) </Frame> ## Die Teile des Bildschirms Der Composer am unteren Rand trägt den Agent-Picker, den Modell-Picker (**Auto** lässt Tale für dich wählen) und das Nachrichtenfeld. **Neuer Chat** in der Sidebar startet einen frischen Chat; **Verlauf anzeigen** öffnet die Liste jedes Chats, den du fortsetzen kannst. Der Canvas öffnet rechts vom Thread, wenn der Agent etwas produziert, das die Inline-Ansicht nicht halten kann — langer Code, ein Diagramm, ein strukturiertes Dokument. ## Seiten in diesem Abschnitt <CardGroup cols="2"> <Card title="Chat-Grundlagen" icon="message-circle" href="/de/platform/chat/basics"> Was zwischen dem Senden und der landenden Antwort passiert — Composer, Modell-Auflösung, Streaming, Zitate. </Card> <Card title="Anhänge" icon="paperclip" href="/de/platform/chat/attachments"> Unterstützte Dateitypen, wo Uploads landen, wann Inhalt indiziert und wann er wörtlich eingefügt wird. </Card> <Card title="Agents im Chat" icon="bot" href="/de/platform/chat/agents-in-chat"> Agents wählen, einmalig versus dauerhaft, mitten im Chat wechseln, Sub-Agent-Aufrufe. </Card> <Card title="Arena-Modus" icon="swords" href="/de/platform/chat/arena-mode"> Modell-Vergleich nebeneinander, und wie Bewertungen in die Feedback-Analyse einfließen. </Card> <Card title="Sprachmodus" icon="mic" href="/de/platform/chat/voice-mode"> Sprechen statt Tippen — die STT- und TTS-Übergaben und die Datenschutzgrenze. </Card> <Card title="Geteilte Chats" icon="share-2" href="/de/platform/chat/shared-threads"> Einen Chat mit dem Rest der Org teilen, einen geteilten Chat in einen eigenen forken. </Card> <Card title="Einstiege und Prompts" icon="list-plus" href="/de/platform/chat/starters-and-prompts"> Die Gesprächseinstiege der Agents und die Prompt-Bibliothek. </Card> <Card title="Canvas-Bereich" icon="panel-right" href="/de/platform/chat/canvas-pane"> Wann der Canvas öffnet, und was einen Canvas statt einer Inline-Darstellung bekommt. </Card> </CardGroup> ## Wo das hineinpasst Chat ist die Oberfläche, der jedes andere Platform-Feature letztlich dient. Agents formen seine Antworten, Wissen füttert seine Zitate, Genehmigungen unterbrechen ihn für menschliche Prüfungen, Konversationen ist eine Schwester-Inbox für Kundenkanäle statt der eigenen Threads. Die Seite, die du dir als Erstes merken solltest, ist [Chat-Grundlagen](/de/platform/chat/basics) — sobald du den Pfad vom Composer zur Antwort verstanden hast, liest sich jede andere Chat-Seite als Variation davon. # Einstiege und Prompts Source: https://tale.dev/docs/de/platform/chat/starters-and-prompts Ein frischer Chat zeigt zwei Oberflächen jenseits des Composers: die **Gesprächseinstiege** des Agents (Beispiel-Prompts zum Antippen) und die **Prompt-Bibliothek** (deine gespeicherten Prompts). Beide verwandeln das Problem des leeren Bildschirms — „was soll ich überhaupt fragen" — in einen einzigen Klick, der funktionierenden Text in den Composer legt. Diese Seite deckt beide Oberflächen ab. Sie wohnen in der UI aus gutem Grund nah beieinander: Einstiege sind die kuratierten Einstiegspunkte des Agent-Autors, die Bibliothek ist dein persönlicher Vorrat, und die meisten Teams nutzen am Ende beides zusammen. ## Gesprächseinstiege <Frame caption="Ein frischer Chat mit den Gesprächseinstiegen des gewählten Agents — ein Tipp legt den Text in den Composer."> ![Der leere Bildschirm eines neuen Chats zeigt die vier Gesprächseinstiege des Assistenten über dem Composer.](/images/platform/chat-starters-empty.webp) </Frame> Jeder Agent kann bis zu vier **Gesprächseinstiege** mitbringen — kurze Beispiel-Prompts, die der Autor des Agents als gute Einstiegspunkte ausgesucht hat. Sie erscheinen auf dem leeren Chat-Bildschirm, wenn der Agent gewählt ist; ein Tipp legt den Text in den Composer, und du kannst ihn vor dem Senden bearbeiten. Einstiege gehören zum Agent, nicht zum Chat — derselbe Agent zeigt überall dieselben Einstiege. Agent-Autoren pflegen die Einstiege auf dem Tab **Gesprächseinstiege** im Editor des Agents; die Autorenseite steht unter [Gesprächseinstiege](/de/platform/agents/conversation-starters). Mitglieder sehen, was der Autor veröffentlicht hat; einen Override pro User gibt es nicht. ## Die Prompt-Bibliothek Die **Prompt-Bibliothek** ist deine persönliche Sammlung wiederverwendbarer Prompts. Speichere die Nachricht, die du gerade senden willst, mit **Prompt speichern**; ruf sie später mit **Prompt-Bibliothek** am Composer wieder ab. Prompts können Platzhalter tragen, deren Werte die Bibliothek beim Einfügen abfragt — aus einer Vorlage „Übersetze das Folgende ins Englische" wird so ein Workflow mit einem Tipp. Gespeicherte Prompts sind standardmäßig privat. Teilst du einen Prompt mit der Org, erscheint er in der Bibliothek aller; die Prompt-Liste der Org lebt zum Stöbern und Taggen in der [Prompt-Bibliothek](/de/platform/workspace/prompt-library) (der Workspace-Seite). ## Kategorien Sowohl Einstiege als auch Prompts können eine Kategorie tragen — ein kurzes Tag wie `Vertrieb`, `Support`, `Marketing`, das sie im Picker gruppiert. Kategorien sind org-definiert und werden unter den Einstellungen verwaltet; ein Agent oder Prompt ohne Kategorie sitzt im Standard-Bucket. ## Wo das hineinpasst Einstiege und Prompts sind das Gerüst gegen den leeren Bildschirm rund um Chat. Die Bibliotheks-Hälfte überschneidet sich mit der [Prompt-Bibliothek](/de/platform/workspace/prompt-library) — dieselben Daten, andere Oberfläche. Die Einstiege wohnen am Agent und werden auf seiner Seite [Gesprächseinstiege](/de/platform/agents/conversation-starters) gepflegt. Welche Seite du als Nächstes liest, hängt davon ab, auf welcher Seite du stehst — Autor oder User. # Chat-Grundlagen Source: https://tale.dev/docs/de/platform/chat/basics Diese Seite ist das mentale Modell für alles im Chat-Tab. Sie benennt die Teile des Composers, verfolgt eine Nachricht vom Tastendruck bis zur gestreamten Antwort und erklärt, wie ein Chat gespeichert wird, sobald er landet — lies sie einmal, und die übrigen Chat-Seiten lesen sich als Variationen desselben Ablaufs. <Frame caption="Der Chat-Tab mit einer gestreamten Antwort über dem Composer."> ![Ein Chat-Thread zeigt eine Nutzerfrage zu Onboarding-Feedback und eine Assistenten-Antwort mit einer Markdown-Tabelle aus drei Themen.](/images/platform/chat-thread-reply.webp) </Frame> ## Der Composer Der Composer ist der Eingabestreifen am unteren Bildschirmrand. Drei Bedienelemente zählen: der Agent-Picker links, der Modell-Picker daneben und das Nachrichtenfeld mit **Nachricht senden** rechts. Anhänge kommen per Einfügen, Drag-and-drop oder über den Anhang-Knopf herein — was akzeptiert wird, steht unter [Anhänge](/de/platform/chat/attachments). <Frame caption="Die Bedienelemente des Composers — das Nachrichtenfeld, der Agent-Picker, der Modell-Picker und Senden."> ![Der leere Chat-Composer, dessen Platzhalter zu einer Frage nach Kontakten, Produkten oder Dokumenten einlädt, über einer Werkzeugleiste mit den Knöpfen für Anhang und Prompt-Bibliothek, dem Agent-Picker, dem Modell-Picker und den Knöpfen für Stummschaltung, Mikrofon und Senden.](/images/platform/chat-composer.webp) </Frame> ## Einen Agent wählen Der Agent-Picker filtert nach Namen, während du tippst; der Standard ist ein agentenloser **Assistent**, der das Standard-Chatmodell der Org und kein zusätzliches Wissen und keine Tools nutzt. Wählst du einen Agent vor der ersten Nachricht, bleibt er für den ganzen Chat gesetzt; wählst du einen mitten im Chat, gilt er ab der nächsten Nachricht. <Note> Einen Schalter zurück zu „ohne Agent" gibt es nicht — wähl **Assistent**, um zurückzukehren. Die vollständigen Regeln stehen unter [Agents im Chat](/de/platform/chat/agents-in-chat). </Note> ## Ein Modell wählen Der Modell-Picker listet, was der Agent (oder die Org, wenn kein Agent gewählt ist) erlaubt. Jedes Modell trägt einen Tag — **Chat**, **Vision**, **Bildgenerierung**, **Embedding** —, der signalisiert, wofür es taugt. **Auto** wählt das Primärmodell des Agents; ist das Primärmodell rate-limitiert oder nicht erreichbar, fällt Tale entlang der Failover-Reihenfolge des Agents zurück. <Warning> Wählst du ein Modell ohne Vision, während die Nachricht ein Bild enthält, fällt das Bild stillschweigend weg — die Antwort liest sich, als wäre das Bild nie gesendet worden. </Warning> ## Die Antwort lesen Die Antwort streamt Token für Token herein. Denkt der Agent nach, bevor er antwortet, erscheint eine einklappbare Denkzeile über der Antwort. Tool-Aufrufe rendern als eingeklappte Boxen, die du aufklappen kannst, um zu lesen, was der Agent getan hat; die Ausgabe von **Code ausführen** landet rechts im Canvas, als **Code-Ausgabe** in seinem Dateibaum. Ruft der Agent Wissen ab, hängen sich Zitate an die Sätze, die sie stützen — beim Hovern über ein Zitat erscheint der Quelltitel, ein Klick öffnet die Quelle. Die Instructions des Agents erscheinen nie in der gerenderten Antwort; sie sitzen eine Schicht tiefer und formen Verhalten statt Text. ## Fragen vom Agent Ein Agent mit dem Human-Input-Tool kann mitten in einer Aufgabe innehalten und dich etwas fragen — eine **Frage**-Karte erscheint im Chat mit den Feldern, die der Agent braucht, und die Generierung wartet, bis du antwortest. Füll das Formular aus und klick **Antwort absenden**, oder klick **Anders antworten**, um stattdessen in freiem Text zu widersprechen. War deine Antwort falsch oder unvollständig, klick auf der beantworteten Karte **Antwort bearbeiten** — das Formular öffnet sich vorausgefüllt, und **Antwort aktualisieren** lässt den Agent erneut laufen, wobei die korrigierte Antwort die alte ersetzt. Die Karte behält jede frühere Antwort: Blätter mit den Pfeilen neben der Antwort durch die Versionen, genau wie bei bearbeiteten Nachrichten. ## Konversationen versus Chats Innerhalb von Chat ist die Einheit ein **Chat** — das Wort, das jede Schaltfläche und jeder Toast verwendet. Das Datenmodell dahinter heißt `threads`, und der URL-Slug ist `threads/$threadId`; die Docs folgen der UI und sagen in der Prosa „Chat". Die Kundenkanal-Inbox, die eine installierte E-Mail-Automatisierung hinzufügt, ist eine andere Oberfläche — eine Konversation dort ist ein Kunden-Thread, kein Chat; die Inbox-Bedeutung steht unter [Mitgelieferte Automatisierungen](/de/platform/automations/builtin). ## Verlauf und Suche **Verlauf anzeigen** über dem Composer öffnet die Verlaufs-Sidebar — jeder Chat, den du in dieser Org fortsetzen kannst, der neueste zuoberst; eine Auswahl öffnet das volle Transkript. Die Suche dort filtert nach Titel; Volltextsuche über Nachrichtentexte ist eine Pro-Chat-Operation, nicht org-weit. Einen Chat umzubenennen setzt einen eigenen Titel, der den modellgenerierten überschreibt; einen Chat zu löschen verschiebt ihn in den [Papierkorb](/de/platform/admin/governance/trash), wo die Aufbewahrung ihn nach der Schonfrist wegräumt. ## Wo das hineinpasst Chat-Grundlagen ist die Seite, die alles andere in diesem Abschnitt verfeinert: [Agents im Chat](/de/platform/chat/agents-in-chat) vertieft den Picker, [Anhänge](/de/platform/chat/attachments) den Upload, [Sprachmodus](/de/platform/chat/voice-mode) die STT- und TTS-Übergaben rund um denselben Composer. Wenn du hier bist, um einen Agent zu bauen statt einen zu nutzen, spring zu [Agent-Konzepte](/de/platform/agents/concepts) — das Vier-Knöpfe-Modell ist die Grundlage, auf der jeder Chat mit einem Agent steht. # Arena-Modus Source: https://tale.dev/docs/de/platform/chat/arena-mode Der Arena-Modus führt dasselbe Prompt parallel gegen zwei Modelle aus und fragt dich, welche Antwort besser ist. Die Bewertung fließt in die Feedback-Analyse der Org; mit der Zeit zeigen die Daten, welches Modell das Team für welche Art von Frage tatsächlich bevorzugt — getrennt vom Bauchgefühl. Greif zur Arena, wenn die Modellwahl eine Debatte statt einer Entscheidung war — Antworten nebeneinander zu vergleichen bricht das Patt mit Belegen statt mit Meinungen. Für gewöhnliche Arbeit reicht der reguläre Modell-Picker; der Wert der Arena sind die Bewertungen, die sie produziert, nicht die Vergleichsansicht selbst. ## Wie die Arena rendert Öffne das Plus-Menü des Composers und wähl **Arena-Modus** — der Composer bekommt zwei Modell-Picker mit den Beschriftungen **Modell A** und **Modell B**. Eine Nachricht zu senden führt beide Modelle parallel aus; der Bildschirm teilt sich, und jede Antwort streamt in ihre eigene Spalte. Sind beide fertig, erscheint unter den Spalten eine Bewertungszeile mit vier Knöpfen: **A ist besser**, **B ist besser**, **Unentschieden**, **Beide schlecht**. <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.](/images/platform/chat-arena-split.webp) </Frame> <Note> Die Arena braucht einen konkreten Agent — wähl im Agent-Picker einen aus statt **Auto**, bevor du sie aktivierst. </Note> ## Die Kontrahenten wählen Die beiden Picker sind unabhängig — jedes chat-getaggte Modell, das die Policy des Agents erlaubt, ist auf jeder Seite zulässig. Dasselbe Modell auf beiden Seiten zu wählen ist erlaubt (nützlich, um Temperaturunterschiede zu testen, wenn der Agent das freigibt), aber die meisten Vergleiche spannen über Anbieter oder Größen. Die Instructions, das Wissen und die Tools des Agents gelten für beide Spalten; nur das zugrunde liegende Modell unterscheidet sich. ## Eine Bewertung abgeben Die Bewertung ist ein einzelner Klick. **A ist besser** und **B ist besser** erklären sich selbst; **Unentschieden** ist für ungefähr gleich gute Antworten; **Beide schlecht** für den Fall, dass keine akzeptabel ist. Der Knopf, den du klickst, speichert die Bewertung und löst den Chat zur gewinnenden Spalte hin auf — die nächste Nachricht, die du sendest, geht nur an dieses Modell. **Unentschieden** oder **Beide schlecht** lässt beide Spalten für eine weitere Runde aktiv. ## Wo Bewertungen auftauchen Bewertungen laufen unter **Arena-Urteile** in der [Feedback-Analyse](/de/platform/admin/governance/feedback-analytics) zusammen, neben einer Tabelle **Top Modell-Duelle**, die Paarungen nach Gewinnrate ordnet. Die Daten sind org-gebunden, nicht pro User — die Bewertungen eines kleinen Teams können also die Defaults eines großen Teams überwiegen, wenn ein Admin die Tabelle nutzt, um das Standardmodell der Org zu setzen. ## Wann du danach greifst | Nutz … wenn | Arena-Modus | Regulärer Modell-Picker | | -------------------------------------------------------------------- | ----------- | ----------------------- | | Du entscheidest, welches Modell zum Standard werden soll | ✓ | | | Du vermutest eine Modell-Regression nach einem Upgrade | ✓ | | | Du weißt schon, welches Modell du willst; du willst nur eine Antwort | | ✓ | | Die Anfrage ist kurz und gewöhnlich | | ✓ | ## Wo das hineinpasst Die Arena ist die leichtgewichtige Rückkopplungsschleife auf der Modellwahl. Die schwerere Oberfläche ist die [Feedback-Analyse](/de/platform/admin/governance/feedback-analytics) — dort werden deine Bewertungen zu einem Diagramm, mit dem jemand später über Defaults streitet. Wenn du derjenige bist, der die Tabelle später liest, dreh vorher eine Handvoll Arena-Runden; die selbst abgegebenen Bewertungen sagen dir, ob die Rahmung der Tabelle deine Erfahrung trifft. # Sprachmodus Source: https://tale.dev/docs/de/platform/chat/voice-mode Der Sprachmodus verwandelt den Composer in ein Mikrofon. Du sprichst, Tale transkribiert, der Agent antwortet in Text, und die Antwort wird laut vorgelesen. Die ganze Schleife ist freihändig — nützlich, wenn du unterwegs bist, fährst (legal), kochst oder schlicht müde vom Tippen bist. Der Sprechpfad des Composers durchquert zwei Modell-Anbieter (Speech-to-Text, dann Text-to-Speech) und ein bis zwei Agent-Aufrufe dazwischen. Zu wissen, welcher Anbieter welches Stück des Audios hält, ist der Unterschied zwischen „das ist praktisch" und „das ist leichtsinnig" für die Daten deiner Org. ## Wie der Sprachmodus läuft Tipp auf das Mikrofonsymbol am Composer, und die Aufnahme startet; nochmal tippen stoppt sie. Tale lädt den Audioclip hoch, das Speech-to-Text-Modell transkribiert ihn, und das Transkript wird die nächste Nachricht im Chat — genau, als hättest du sie getippt. Der Agent antwortet in Text; sobald die Antwort fertig ist, routet Tale sie an ein Text-to-Speech-Modell und spielt das Audio zurück. Während die Antwort streamt, beendet **Gestoppt** die Wiedergabe vorzeitig; **Sprachausgabe abspielen** spielt die letzte Antwort erneut ab. ## STT- und TTS-Übergaben Zwei Modellwahlen zählen, und sie werden separat vom Chat-Modell konfiguriert. **Speech-to-Text** läuft einmal pro gesprochener Nachricht — das Audio wird hochgeladen, transkribiert, und das Transkript ist das, was der Agent sieht. **Text-to-Speech** läuft einmal pro Antwort — Tale teilt die Antwort in Sprachausgabe-Segmente und streamt Audio zurück. Der Agent selbst bleibt unverändert; der Sprachmodus ist ein Wrapper um denselben Composer. ## Stimmen wählen Jeder Agent kann in seinen Einstellungen eine bevorzugte Stimme festlegen; ohne agent-eigene Wahl nutzt der Sprachmodus die Standardstimme der Org. Stimmen sind an bestimmte TTS-Anbieter gebunden — den Anbieter zu wechseln wechselt die verfügbaren Stimmen. Nutzt ein Chat einen Agent, dessen Stimmen-Anbieter nicht mehr konfiguriert ist, fällt Tale auf die Standardstimme der Org zurück, statt die Antwort scheitern zu lassen. ## Die Datenschutzgrenze Der aufgezeichnete Audioclip verlässt dein Gerät. Er wird in Tales Speicher hochgeladen, an den konfigurierten Speech-to-Text-Anbieter gesendet, und das Transkript liegt zusammen mit den getippten Nachrichten im Chatverlauf. Das Audio selbst bleibt gemäß der Aufbewahrungspolicy der Org erhalten. Antworten gehen als Klartext an den Text-to-Speech-Anbieter hinaus; die Audio-Antwort wird auf dein Gerät gestreamt und standardmäßig nicht auf der Festplatte gespeichert. <Warning> Orgs mit strengen Regeln für Daten außerhalb der Region sollten STT- und TTS-Anbieter in derselben Region wählen wie den Rest des Stacks — siehe [Daten-Residenz](/de/cloud/data-residency). </Warning> ## Wann Sprache Text schlägt Sprache ist schneller als Tippen für kurze, gesprächige Fragen und dramatisch langsamer für Code, Listen oder alles, was du herauskopieren würdest. Sprachantworten haben ein Chunk-Limit — lange Antworten brechen mittendrin ab und zeigen einen Hinweis. Greif zur Sprache, wenn die Antwort einmal gehört und vergessen wird; greif zum Text, wenn die Antwort überflogen oder gespeichert werden muss. ## Wann du danach greifst | Nutz … wenn | Sprachmodus | Text | | ----------------------------------------------------------------- | ----------- | ---- | | Du hast die Hände voll und willst einen schnellen Fakt | ✓ | | | Die Antwort wird eine lange Liste oder ein Codeblock | | ✓ | | Die Antwort des Agents fließt in eine spätere schriftliche Arbeit | | ✓ | | Du übst eine Sprache und willst sie hören | ✓ | | ## Wo das hineinpasst Der Sprachmodus ist eine von drei Eingabeformen am selben Composer: Text (der Standard), Anhänge und Sprache. Die Datenschutz-Geschichte zählt hier am meisten, weil zwei zusätzliche Anbieter die Daten berühren — die nächste Lektüre ist daher [Daten-Residenz](/de/cloud/data-residency) auf Cloud oder [Konfiguration → Anbieter](/de/self-hosted/configuration/providers) auf selbst gehosteten Instanzen, je nachdem, welche Edition du betreibst. # Agents im Chat Source: https://tale.dev/docs/de/platform/chat/agents-in-chat Einen Agent im Chat zu wählen ist der Unterschied zwischen einer Frage an den generischen Assistenten und einer Frage an etwas, das die Org für eine Domäne geformt hat. Der Agent-Picker ist das meistgenutzte Bedienelement im Composer; welche Agents erscheinen, wann ein Agent gesetzt bleibt und was beim Wechsel mitten im Chat passiert, ist das Thema dieser Seite. <Frame caption="Der geöffnete Agent-Picker über dem Composer — Auto, die installierten Agents und der Katalog-Shortcut."> ![Der über dem Chat-Composer geöffnete Agent-Picker zeigt ein Suchfeld, einen Auto-Eintrag, den ausgewählten Assistenten, einen Eintrag namens Automation Assistant und einen Knopf Automatisierungen durchsuchen.](/images/platform/chat-agent-picker.webp) </Frame> ## Der Agent-Picker Klick auf den Agent-Chip am Composer (sein zugänglicher Name ist **Agent auswählen**), und der Picker öffnet mit **Agents suchen** obenauf. Die Liste zeigt **Auto** — Tale routet jede Nachricht an den Agent, der am besten passt — gefolgt von jedem Agent, auf den du Zugriff hast und der als **Im Chat sichtbar** markiert ist; Coding-Agenten bekommen einen eigenen Abschnitt **Coding-Agenten**, sobald welche sichtbar sind. Agents ohne diesen Schalter existieren in der Org, tauchen hier aber nie auf, was die Liste kurz hält. **Automatisierungen durchsuchen** unten führt zum [Automatisierungen-Katalog](/de/platform/automations/catalog) — neue Agents kommen als Teil einer Automatisierung an, die du installierst. ## „Im Chat sichtbar" Jeder Agent hat einen Schalter **Im Chat sichtbar** auf der Seite **Allgemein** seines Editors. Ihn auszuschalten deaktiviert den Agent nicht — Automatisierungen und Workflows können ihn weiterhin aufrufen, und Sub-Agent-Aufrufe aus anderen Agents funktionieren weiter — es versteckt den Agent nur vor dem Chat-Picker. Der Grund: Orgs landen bei Dutzenden Agents, die kaum jemand je von Hand wählt (Hilfs-Agents, die andere Agents rufen; Agents, die an einen bestimmten Workflow gebunden sind), und sie alle anzuzeigen würde die Alltagsauswahl ertränken. ## Einmalig versus dauerhaft Wählst du einen Agent **vor** der ersten Nachricht eines Chats, bleibt er gesetzt — jede folgende Nachricht im selben Chat geht an denselben Agent. Wählst du einen Agent **mitten im Chat**, gilt er ab der nächsten Nachricht und für alles danach, bis du wieder wechselst. <Note> Eine Geste „diesen Agent einmal nutzen und zurückspringen" gibt es nicht — um den Chat zurückzugeben, wähl im Picker explizit **Assistent** (oder **Auto**). Das Transkript behält den Agent pro Nachricht, ein Chat mit einem Wechsel mittendrin liest sich also wie zwei Agents, die zusammenarbeiten. </Note> ## Mitten im Chat wechseln Wissen und Tools des Agents wechseln mit dem Picker, der Gesprächsverlauf aber nicht. Der neue Agent liest alles, was davor war — deine Nachrichten und die Antworten des vorherigen Agents — und macht von dort weiter. Das ist nützlich für Übergaben: Ein Triage-Agent beantwortet die erste Nachricht, du wechselst für die Nachfragen zu einem Spezialisten, und der Spezialist hat den vollen Kontext, ohne dass jemand kopieren und einfügen muss. ## Sub-Agent-Aufrufe Die Instructions eines Agents können ein Sub-Agent-Tool enthalten; wenn ja, kann der primäre Agent einen Teil der Arbeit delegieren, ohne dass du irgendetwas wählst. Sub-Agent-Aufrufe rendern in der Antwort als eingeklappte Tool-Aufrufe — du siehst, was delegiert wurde und was zurückkam, nicht eine vollständige zweite Konversation. Die Delegationsregeln und das Loop-Vermeidungsmodell leben auf [Agent-Delegation](/de/platform/agents/delegation). ## Wann welche Form passt | Nutz … wenn | Chat | Projekte | Konversationen | | --------------------------------------------------- | ---- | -------- | -------------- | | Persönliche Aufgabe, einmalige Frage | ✓ | | | | Geteilter Workspace für ein Team, laufende Threads | | ✓ | | | Eingehendes aus einem Kundenkanal (E-Mail, Webhook) | | | ✓ | ## Wo das hineinpasst Agents im Chat ist die nutzerzugewandte Hälfte der Agents-Geschichte — was der Picker tut, was erscheint, wann ein Agent gesetzt bleibt. Die bauzugewandte Hälfte ist [Agent-Konzepte](/de/platform/agents/concepts): die vier Knöpfe, die bestimmen, was ein Agent tut, sobald er gewählt ist. Wenn du hier bist, um den Agent zu bauen, den du dir im Picker wünschst, ist das die nächste Lektüre. # Anhänge Source: https://tale.dev/docs/de/platform/chat/attachments Anhänge lassen einen Chat auf eine Datei verweisen, ohne dich in einen anderen Tab zu schicken. Du fügst ein, ziehst herein oder wählst **Fotos & Dateien hinzufügen** im Plus-Menü des Composers; die Datei reist mit der Nachricht mit, und Tale routet sie in die richtige Pipeline. Die meisten Dateitypen landen wörtlich im Input des Modells; große oder strukturierte Dateien werden indiziert und ausschnittweise gelesen. Diese Seite deckt nur den Upload-Mechanismus am Composer ab. Dokumente, die in [Wissen](/de/platform/knowledge/documents) hochgeladen werden, folgen einem separaten Ablauf mit persistenter Indizierung — Chat-Anhänge sind an den Chat gebunden, der sie empfangen hat. ## Ein durchgespielter Upload Füg ein PDF in den Composer ein. Der Composer zeigt einen Chip mit dem Dateinamen und einem Spinner; der Chip wird zu **Hochgeladen**, sobald die Datei in Tales Speicher gelandet ist. Klick **Nachricht senden**, und der Agent erhält eine extrahierte Textansicht des PDFs inline mit deinem Prompt. Ist die Datei größer als das Inline-Kontextbudget, indiziert Tale sie, und der Agent liest Chunks bei Bedarf über sein Retrieval-Tool. ## Unterstützte Typen Drei Familien: **Bilder**, **strukturierte Dokumente** (PDF, DOC/DOCX, ODT, XLS/XLSX, PPT/PPTX) und **textartige Dateien** (Plaintext, Markdown, Quellcode, CSV, JSON, YAML). Bilder gehen an das Vision-Modell, das der Chat nutzt; der Modell-Picker muss auf einem vision-fähigen Modell stehen, sonst fällt das Bild stillschweigend weg. Strukturierte Dokumente werden zu Text extrahiert — Diagramme, gescannte Seiten und eingebettete Objekte sind Best-Effort. Textartige Dateien landen wörtlich. ## Wo Uploads leben Jeder Anhang wird in Tales Objektspeicher abgelegt und an den Chat gebunden, der ihn empfangen hat, und zusätzlich in die Sandbox des Chats unter `/user/uploads/<name>` kopiert. Auf dieser zweiten Kopie arbeiten die `file_read`-, `file_list`- und `run_code`-Tools des Agents: auf den echten Bytes, nicht nur auf der extrahierten Textansicht, die inline mit deinem Prompt mitreist. Den Chat zu löschen verschiebt die Anhänge zusammen mit dem Nachrichtenverlauf in den [Papierkorb](/de/platform/admin/governance/trash); Wiederherstellen bringt sie zurück. Eine separate Bibliothek für Chat-Anhänge gibt es nicht — um ein Dokument über viele Chats zu teilen, lad es in [Wissen](/de/platform/knowledge/documents) hoch und bind es an einen Agent. ## RAG versus wörtlich Kleine Textdateien und strukturierte Dokumente unter dem Inline-Budget des Agents werden wörtlich eingefügt. Größere werden in Chunks geteilt, eingebettet und indiziert; der Agent ruft die relevanten Chunks zur Antwortzeit ab und zitiert sie. Die Grenze hängt vom Modell ab — Long-Context-Modelle schlucken mehr im Ganzen. Ruft der Agent aus einem Anhang ab, statt ihn ganz zu lesen, zeigen die Zitate auf Chunk-Bereiche in der Originaldatei. ## Wissensdokumente mit @ referenzieren <Frame caption="Ein getipptes @ öffnet den Wissensdatenbank-Picker über dem Composer."> ![Der Chat-Composer zeigt ein getipptes @-Zeichen und den geöffneten Wissensdatenbank-Picker mit drei indexierten Textdokumenten.](/images/platform/chat-mention-picker.webp) </Frame> Tippst du `@` in den Composer, öffnet sich ein Picker über das indexierte Wissen der Org — aufgeteilt in einen Abschnitt **Dokumente** und einen Abschnitt **Ordner**. Tipp weiter, um nach Namen zu filtern; `@Datei` heftet ein Dokument unter einem **Wissen**-Chip an, `@Ordner` einen Ordner samt allem darunter Indexierten unter einem **Ordner**-Chip. Beim Senden prüft Tale deinen Zugriff, begrenzt das Retrieval dieser Antwort auf genau die angehefteten Einträge — ein Ordner expandiert zu den Dateien seines Unterbaums — und fügt die relevanten Passagen ein, selbst wenn der Wissensmodus des Agents aus ist, denn eine explizite Erwähnung schlägt die Retrieval-Konfiguration des Agents. Bis zu fünf Einträge, Dokumente und Ordner zusammen, lassen sich pro Nachricht anheften. Die Chips sind die Quelle der Wahrheit: Löschst du den `@Titel`-Text aus der Nachricht, bleibt der Verweis angeheftet — entfern stattdessen den Chip. Der Picker bietet nur Dokumente an, deren Indexierung abgeschlossen ist und auf die deine Teams Zugriff haben. In einem Projekt-Chat listet er zusätzlich die Dateien und Ordner des Projekts, zuoberst; die Dateien eines Projekts bleiben auf das Projekt begrenzt und tauchen im `@`-Picker eines Chats außerhalb davon nie auf — siehe [Projekt-Dateien verwalten](/de/platform/projects/manage-files). Der Verweis gilt pro Nachricht; eine Nachfrage ohne Erwähnungen fällt auf den normalen Wissens-Scope des Agents zurück. ## Wo das hineinpasst Anhänge sind der leichtgewichtige, chat-gebundene Weg, eine Datei in eine Antwort zu bringen. Das schwergewichtige, org-gebundene Äquivalent ist [Dokumente](/de/platform/knowledge/documents) — dieselbe Indizierungs-Pipeline, aber an Agents statt an einen einzelnen Chat gebunden. Welche Seite du als Nächstes liest, hängt davon ab, was du vorhast — zählt die Datei einmal, häng sie hier an; wird sie wieder zählen, lad sie in Wissen hoch und lass einen Agent aus jedem Chat darauf verweisen. # Canvas-Bereich Source: https://tale.dev/docs/de/platform/chat/canvas-pane Der **Canvas** ist ein zweiter Bereich, der rechts vom Chat-Thread öffnet. Er erscheint, wenn die Antwort Inhalt enthält, den der lineare Thread schlecht halten kann — ein langer Codeblock, ein Mermaid-Diagramm, ein strukturiertes Dokument, ein ausführbares Python-Skript. Inline-Antworten bleiben kurz und lesbar; alles andere zieht aus dem Weg. Der Canvas ist kein reichhaltigerer Composer und kein Ort, an dem du von Hand bearbeitest. Er ist eine lebendige Ansicht des Chat-Workspace — die Dateien, die der Agent schreibt, die Dateien, die du hochlädst, und die Dateien, die Code-Läufe erzeugen — und du siehst sie, ohne fragen zu müssen. ## Was der Canvas ist Der Canvas öffnet automatisch, sobald eine Antwort zum ersten Mal canvas-würdigen Inhalt produziert. Er hat zwei Teile: links einen Dateibaum, rechts einen Betrachter. Der Baum gruppiert die Workspace-Dateien des Chats nach ihrer Herkunft — **KI-Dateien**, die der Agent geschrieben hat (`/user/code`), **Hochgeladen** für Dateien, die du angehängt oder mit `@` angeheftet hast (`/user/uploads`), und **Code-Ausgabe** für das, was ein Lauf erzeugt hat (`/user/output`); leere Gruppen bleiben ausgeblendet. Wähl eine Datei, und sie öffnet im Betrachter, wo du zwischen **Quelltext** und **Vorschau** wechselst, um rohen Code zu lesen oder das gerenderte Ergebnis zu sehen, und **Herunterladen** genau diese Datei speichert. ## Wann er automatisch öffnet Der Canvas öffnet für mehrere Render-Arten, die den Inline-Thread überfüllen würden: **Code** (jede Sprache), **HTML**, **Mermaid**-Diagramme, **SVG**, lange **Markdown**-Dokumente aus der Hand des Agents und ausführbare Skripte — **Python (Sandbox)**, **Node (Sandbox)**, **Skript (Sandbox)**. `run_code` läuft über den geteilten Workspace des Chats — es liest die Skripte, die der Agent unter `/user/code` geschrieben hat, und erntet, was der Lauf in `/user/output` ablegt, sodass Resultate als **Code-Ausgabe**-Zeilen im Dateibaum erscheinen statt nur neben dem Skript; ein Lauf kann auch bloß Pakete als eigenen Schritt installieren und zeigt dabei **Abhängigkeiten installieren**. Nur vom Agent geschriebene Dateien und Code-Ausgaben öffnen den Canvas automatisch — Dateien, die du hochlädst, erscheinen im Baum, reißen aber nicht den Bildschirm an sich. Kurze Snippets, die der Inline-Thread halten kann, lösen den Canvas nicht aus — ein Skript mit zwanzig Zeilen rendert inline mit eigenem **Kopieren**-Knopf, wie unten. <Frame caption="Ein kurzes Skript bleibt inline — der Canvas ist für Ausgaben, die dem Thread entwachsen."> ![Eine Chat-Antwort zeigt einen syntaxhervorgehobenen Python-Codeblock, der inline mit einem Kopieren-Knopf gerendert wird, ohne dass sich der Canvas-Bereich öffnet.](/images/platform/chat-code-reply.webp) </Frame> ## Im Canvas bearbeiten Der Canvas ist eine Render-Oberfläche für das, was der Agent produziert hat. Den gerenderten Inhalt zu bearbeiten heißt, den Agent um eine Revision zu bitten — eine Folgenachricht im Thread („setz den Timeout auf 30 Sekunden", „mach das Diagramm horizontal") löst eine neue Generierung aus, die den Canvas-Inhalt ersetzt. Einen Direkt-Bearbeiten-Modus gibt es nicht; der Agent besitzt die Dateien, die er schreibt, und die Dateien, die du hochlädst, bleiben genau so, wie du sie gesendet hast. ## Persistenz über den Chat hinweg Der Canvas-Inhalt gehört zum Chat, nicht zu einer separaten Datei. Den Chat später wieder zu öffnen öffnet den Canvas mit dem letzten Inhalt; zu einem anderen Chat zu wechseln schließt den Canvas-Bereich, bis dieser Chat eigenen Canvas-Inhalt produziert oder trägt. Den Chat mit **Chat teilen** zu teilen trägt den Canvas mit hinüber — Betrachter sehen denselben Wechsel zwischen Quelltext und Vorschau, im Lesemodus. ## Wo das hineinpasst Der Canvas ist die Antwort auf „was passiert, wenn die Antwort zu groß für den Thread ist". Er komponiert mit allem anderen im Chat — Agents, Anhängen, Sprache, geteilten Chats — ohne dass diese Features von ihm wissen müssten. Die nächste Lektüre, die manchmal zählt: [Ein eigenes Tool bauen](/de/tutorials/developer/build-a-custom-tool) führt auf einer frischen Instanz einen Agent von Anfang bis Ende durch, der ausführbares Python im Canvas produziert. # Integrationen Source: https://tale.dev/docs/de/platform/integrations/overview Integrationen sind die Brücken zwischen Tale und dem Rest deines Stacks: Agents rufen sie als Tools auf, Workflows rufen sie in Schritten auf, und die Wissens-Pipeline zieht Dokumente durch sie hindurch. Die Organisation verbindet jede genau einmal unter **Einstellungen > Integrationen**; von da an kann alles in Tale sie nutzen, ohne sich neu zu authentifizieren. Diese Übersicht benennt den mitgelieferten Katalog und die zwei Wege, ihn zu erweitern. <Frame caption="Einstellungen > Integrationen auf dem Tab Alle Integrationen — der volle Katalog, jede Karte ein Verbinden entfernt."> ![Die Seite Einstellungen Integrationen mit einem Suchfeld, einem Button Integration hinzufügen und einem Kartenraster aus zwölf Diensten, darunter Confluence, GitHub, Gmail, Slack und Twilio.](/images/platform/integrations-catalog.webp) </Frame> ## Der Katalog Die Seite hat zwei Tabs — **Verbunden** zeigt, was die Organisation bereits nutzt, **Alle Integrationen** den vollen Katalog mit einem Suchfeld. Die Beschreibung jeder Karte ist der ehrliche Einzeiler dessen, was dir das Verbinden bringt: | Integration | Was sie tut | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Confluence** | Importiert Confluence-Cloud-Seiten in Tales Wissensdatenbank. | | **Discord** | Postet Nachrichten und verwaltet Kanäle in deinem Discord-Server. | | **GitHub** | Verwaltet Repositories, Issues und Pull Requests auf GitHub. | | **Gmail** | Liest, sendet und organisiert E-Mails in Gmail. | | **Google Drive** | Importiert Dateien aus Google Drive in Tales Wissensdatenbank. | | **IMAP / SMTP Mailbox** | Verbindet einen privaten IMAP- und SMTP-Mailserver mit dem Posteingang — kein Gmail- oder Outlook-Konto nötig; der Versand kann über ein separates SMTP-Relay (Resend, SendGrid, Amazon SES, …) laufen statt über den Postfach-Login. | | **Microsoft Outlook** | Verwaltet Outlook-Mail, -Kalender und -Kontakte. | | **Shopify** | Synchronisiert Produkte, Kunden und Bestellungen aus deinem Shopify-Shop. | | **Slack** | Sendet Nachrichten und interagiert mit Kanälen in Slack. | | **Tavily** | Websuche und Seitenextraktion in Echtzeit für KI-Recherche. | | **Microsoft Teams** | Sendet Nachrichten und verwaltet Kanäle in Microsoft Teams. | | **Twilio** | Sendet SMS und führt Sprachanrufe mit Twilio. | ## Eine verbinden Klicke auf **Verbinden** auf einer Karte. OAuth-gestützte Dienste führen durch den Einwilligungs-Flow des Anbieters; Token-gestützte fragen im Abschnitt **Authentifizierung** nach dem Zugangsnachweis. Die Detailansicht listet außerdem die Operationen der Integration — die mit **Genehmigung erforderlich** markierten halten im Chat, bis eine Person zustimmt; so bleiben ausgehende Schreibzugriffe nachvollziehbar ([Genehmigungen konfigurieren](/de/platform/approvals/configure)). Dokumente, die über Confluence oder Google Drive hereinkommen, fließen durch dieselbe Indexierungs-Pipeline wie direkte Uploads, und Zitate zeigen zurück auf die Quelle — siehe [Dokumente](/de/platform/knowledge/documents). ## Über den Katalog hinaus erweitern **Integration hinzufügen** lädt einen eigenen Konnektor hoch — ein kleines Paket aus `config.json`, einer `connector.js` oder `.ts` und einem Icon (als `.zip` oder Einzeldateien, 1 MB gesamt). Die Vorschau zeigt vor der Installation seine Operationen, erlaubten Hosts und den Konnektor-Code, und das Ergebnis erscheint im Katalog wie jeder mitgelieferte Eintrag. Wenn kein Konnektor passt und du die Brücke selbst hosten kannst, registriere stattdessen einen [MCP-Server](/de/platform/integrations/mcp-servers) — eine generische Protokolloberfläche statt eines anbieterspezifischen Konnektors. <Note> WebDAV steht nicht in diesem Katalog, weil es in die andere Richtung zeigt: Es serviert Tales Dokumente als Netzlaufwerk an deine Geräte. Siehe [WebDAV](/de/platform/integrations/webdav). </Note> ## Wo das hingehört Integrationen sind der Weg, auf dem Agents auf die Welt außerhalb von Tale wirken. Für Agent-Autoren zeigt [Agent-Tools](/de/platform/agents/tools), wie die Operationen einer Integration als Tools auftauchen; für Genehmiger ist [Genehmigungen konfigurieren](/de/platform/approvals/configure) der Ort, an dem Schreiboperationen angehalten werden; für Builder ohne passenden Konnektor ist [MCP-Server](/de/platform/integrations/mcp-servers) die offene Alternative. # MCP-Server Source: https://tale.dev/docs/de/platform/integrations/mcp-servers Ein MCP-Server ist ein externer Prozess, der Tales Agents über das Model Context Protocol Tools bereitstellt. Wo eine [Integration](/de/platform/integrations/overview) ein anbieterspezifischer Konnektor ist, den Tale mitliefert, ist ein MCP-Server eine generische Brücke, die jeder hosten kann — eine interne API, ein Anbieter ohne Konnektor, ein Skript, das etwas berechnet, was Tales eingebaute Tools nicht können. Du hostest den Server; Tale spricht nur mit ihm. <Frame caption="Das Formular MCP-Server hinzufügen — eine Verbindung und eine Authentifizierungsmethode sind die ganze Registrierung."> ![Der Dialog MCP-Server hinzufügen unter Einstellungen API MCP, ausgefüllt für einen Server für Support-Tickets — Anzeigename Support Tickets, eine einzeilige Beschreibung, Streamable HTTP als Transporttyp, die Server-URL und Keine als Authentifizierungsmethode — über der MCP-Seite, auf der bereits ein Server Internal Wiki registriert ist.](/images/platform/settings-mcp-add-dialog.webp) </Frame> ## Einen Server registrieren Öffne **Einstellungen > API > MCP** und klicke auf **MCP-Server hinzufügen**. Das Formular nimmt: - **Name** und **Anzeigename** — die Kennung und das Label, das Agents und Genehmigungskarten zeigen. - **Transporttyp** — **Streamable HTTP**, **SSE** oder **stdio**. Die HTTP-Transporte nehmen eine **URL** — das Formular markiert eine fehlerhafte URL inline, bevor du speichern kannst; stdio nimmt den Befehl, den Tale startet. - **Authentifizierung** — **Keine**, **API-Key** oder **OAuth 2.0** (Token-URL, Client-ID und -Geheimnis, Bereiche). - **Erlaubte Agents** — welche Agents sich an diesen Server binden dürfen. Standard ist keine Agents; greif zu **Alle Agents** nur, wenn der Server generisch genug ist, dass jeder Agent profitiert. **Server speichern**, dann **Verbindung testen** auf der Zeile, um den Handshake zu prüfen — der Status der Zeile zeigt **Verbunden**, **Getrennt** oder **Fehler** mit der Meldung der Gegenseite. ## Die erkannten Tools Sobald die Verbindung steht, holt Tale das Manifest des Servers und listet es als **Erkannte Tools** — Name und Beschreibung jedes Tools und ob der Server es mit **Genehmigung erforderlich** markiert. Markierte Tools fragen im Chat bei jedem Aufruf durch einen Agent, mit den exakten Argumenten auf der Karte; unmarkierte laufen wie jedes eingebaute Tool. <Warning> Jedes MCP-Tool weitet aus, was deine Agents erreichen können, und die Genehmigungs-Flags stammen vom Autor des Servers — einen Server zu verbinden heißt, seinen Tool-Vertrag anzunehmen. Lies die erkannte Liste, bevor du Agents auf einen Server richtest, den du nicht selbst geschrieben hast. </Warning> ## Aus Agents heraus nutzen Die Tools eines registrierten, aktiven Servers reihen sich in das Tool-Set ein, das Agents aufrufen können; die Anfrage reist durch Tale zu deinem Server, und die Antwort kommt zurück ins Gespräch. Der Server kann auch Ressourcen und Prompts bereitstellen, wo sein Autor sie implementiert — Tools sind die gemeinsame Oberfläche. ## Deaktivieren und entfernen Jede Server-Zeile lässt sich deaktivieren — seine Tools fallen aus den Tool-Sets der Agents heraus, bis du ihn wieder aktivierst; die Registrierung bleibt erhalten. Den Server zu löschen entfernt die Registrierung nach einer Bestätigung vollständig; ihn später erneut hinzuzufügen ist eine frische Registrierung mit einem frischen Manifest-Abruf. ## MCP-Server oder Integration Beide lassen einen Agent über Tale hinausgreifen; der Unterschied ist, wem der Konnektor gehört. Integrationen sind anbieterspezifisch, mitgeliefert und im Katalog gepflegt; MCP-Server sind generisch, und du betreibst sie selbst. Greif zur Integration, wenn eine für das Zielsystem existiert; greif zu MCP, wenn die Brücke dein eigener Code sein soll. ## Wo das hingehört MCP ist die offene Erweiterungsfläche des Agent-Tool-Sets. Die natürlichen nächsten Lektüren sind [Agent-Tools](/de/platform/agents/tools) dafür, wie Tools an einem Agent auftauchen, [Genehmigungen konfigurieren](/de/platform/approvals/configure) für die Flags, die riskante Aufrufe anhalten, und das Tutorial [MCP-Server von Grund auf](/de/tutorials/developer/mcp-server-from-scratch) für den Bau von Anfang bis Ende. # WebDAV Source: https://tale.dev/docs/de/platform/integrations/webdav WebDAV verwandelt Tales Dokumentenspeicher in einen entfernten Ordner, den du wie jedes geteilte Netzlaufwerk einhängst. Der dahinterliegende Speicher ist derselbe, den der Dokumenten-Hub zeigt — was du in den eingehängten Ordner legst, erscheint in der UI, und umgekehrt. Alles Nötige liegt auf einem Panel: **Einstellungen > API > WebDAV** trägt die Verbindungsdaten und den App-Passwort-Generator. <Frame caption="Einstellungen > API > WebDAV — oben die vorbefüllten Verbindungsdaten, darunter der App-Passwort-Generator."> ![Die WebDAV-Einstellungsseite mit einer Verbindungs-URL, einem Benutzernamensfeld mit der Konto-E-Mail, einer Erklärung, dass das Passwort ein erzeugtes App-Passwort ist, und einer App-Passwort-Tabelle mit zwei Einträgen — Design workstation und MacBook Pro, jeder nur mit seinem Präfix und dem Erstellungsdatum — neben einem Erzeugen-Button.](/images/platform/settings-webdav.webp) </Frame> ## Ein App-Passwort erzeugen Der Endpunkt authentifiziert mit App-Passwörtern — kurzen Geheimnissen, die du pro Gerät prägst — weil jeder WebDAV-Client seinen Zugangsnachweis im System-Schlüsselbund ablegt, und dorthin gehört ein begrenztes, widerrufbares Geheimnis statt deines Konto-Passworts. Dein Konto-Passwort funktioniert an diesem Endpunkt nicht. Klicke auf **Erzeugen**, benenne das Passwort nach dem Gerät (`MacBook Finder`, `ops-laptop rclone`) und kopiere es — nutze eines pro Gerät; das vollständige Passwort erscheint nur einmal. Danach behält die Tabelle nur die Bezeichnung und ein kurzes Präfix, genug, um die Zeile wiederzuerkennen, wenn du sie widerrufst. Das Erzeugen verlangt dieselbe Berechtigung, die auch API-Schlüssel schützt; Mitglieder ohne sie bitten einen Admin. Für den Benutzernamen nimm deine Tale-Konto-E-Mail. Der Server prüft tatsächlich nur das Passwort, aber die E-Mail hält Audit-Zeilen lesbar und entspricht dem, was Client-Dialoge erwarten. ## Von deinem Gerät verbinden Die Adresse ist die URL vom Panel — `https://<your-site>/dav/<orgSlug>/documents/`. <Tabs> <Tab title="macOS Finder"> Drücke **⌘K** (Mit Server verbinden), füge die URL ein und melde dich mit deiner E-Mail und dem App-Passwort an. Die Freigabe erscheint in der Seitenleiste; zieh Dateien hinein zum Hochladen, hinaus zum Herunterladen, und benenne um oder lösche direkt an Ort und Stelle. Das erste Auflisten eines großen Baums kann ein paar Sekunden dauern. </Tab> <Tab title="Windows"> Wähle in **Dieser PC** die Option **Netzlaufwerk verbinden**, füge die URL als Ordner ein und wähle **Verbindung mit anderen Anmeldeinformationen herstellen**. Windows deckelt WebDAV-Übertragungen standardmäßig bei 50 MB pro Datei — erhöhe `FileSizeLimitInBytes` unter dem Registrierungsschlüssel `WebClient\Parameters` und starte den WebClient-Dienst neu. Auf einem Nicht-Standard-HTTPS-Port setze `BasicAuthLevel` unter demselben Schlüssel auf `2`. </Tab> <Tab title="iOS Files"> Tippe auf das Dreipunkt-Menü, wähle **Mit Server verbinden** und gib dieselbe URL und dieselben Zugangsdaten ein. Die Dateien-App unterstützt Durchsuchen und Herunterladen; Bearbeiten an Ort und Stelle funktioniert für Formate mit einer iOS-App. </Tab> <Tab title="rclone"> ```bash rclone config create tale webdav \ url=https://<your-site>/dav/<orgSlug>/documents/ \ vendor=other \ user=<your-email> \ pass=$(rclone obscure '<app-password>') rclone copy ./local-folder tale: --progress ``` `vendor=other` ist richtig — Tales Server ist generisch, keine benannte Spielart, die rclone kennt. </Tab> </Tabs> ## Was das eingehängte Laufwerk kann Lese- und Schreibzugriffe spiegeln deine Berechtigungen im Dokumenten-Hub, Dateien, die du hochlädst, landen im Index und in der Suche wie direkte Uploads, und ihr Quellfeld steht auf `webdav` zum Filtern in Audit-Ansichten. Projekt-Dateien sind die Ausnahme: Der **Wissen**-Tab eines Projekts ist auf dieses eine Projekt begrenzt und taucht nie über WebDAV auf, das eingehängte Laufwerk zeigt also nur den org-weiten Dokumenten-Hub. Der Namensraum `.trash/` listet weich gelöschte Dokumente schreibgeschützt — lade zur Wiederherstellung herunter, stelle über die UI wieder her. Editoren, die WebDAV-Locks nehmen (Office, LibreOffice), bekommen sie; ein konkurrierender Schreibzugriff während einer Bearbeitung erhält `423 Locked`. ## Widerrufen Widerrufe ein Passwort mit dem Papierkorb-Symbol auf seiner Zeile — die nächste Anfrage damit wird abgewiesen, andere Geräte bleiben unberührt, und alle Locks, die es hielt, werden freigegeben. Es gibt kein Zurück; präge ein neues Passwort, wenn du die falsche Zeile widerrufst. <Warning> Basic Auth sendet das App-Passwort mit jeder Anfrage. Hänge nur über HTTPS ein, lass das Passwort im Schlüsselbund des Betriebssystems und füge es nie in eine URL der Form `https://user:pass@host/` ein — Shell-Verlauf und Proxy-Logs überleben das Laufwerk. Widerrufe sofort bei jedem Verdacht auf ein Leck. </Warning> ## Wo das hingehört WebDAV ist die gerätezugewandte Tür pro Nutzer zu denselben Daten wie der [Dokumenten-Hub](/de/platform/knowledge/documents); das Drahtprotokoll steht unter [WebDAV-API](/de/develop/webdav-api). Für Maschine-zu-Maschine-Importe sind [API-Schlüssel](/de/platform/admin/api-keys) plus die REST-API meist die bessere Wahl. # Admin Source: https://tale.dev/docs/de/platform/admin/overview Admin ist die Konfigurationsebene von Tale. Sie umfasst die Personen, die sich anmelden dürfen, die Teams, die sie gruppieren, die KI-Anbieter hinter jeder Antwort, die API-Schlüssel, mit denen externer Code mit der Organisation spricht, die Drittanbieter-Integrationen, durch die Agents nach außen greifen, und das Branding, das der Rest der Organisation sieht. Nur Admins und Inhaber sehen das volle Admin-Menü; Entwickler sehen eine Teilmenge, andere Rollen sehen es gar nicht. Diese Seiten beschreiben, was jede Einstellung tut und was sie am laufenden Produkt ändert. Die meisten liest du einmal beim Aufsetzen und besuchst sie wieder, wenn sich etwas ändert — eine neue Person, ein rotierter Schlüssel, ein neuer Anbieter. Die Rollen- und Berechtigungsgeschichte hinter dem ganzen Menü liegt in [Mitglieder und Rollen](/de/platform/admin/members-and-roles); fang dort an, denn jede andere Admin-Seite verweist auf die Rollennamen, die sie definiert. ## Konfigurationsbereiche <CardGroup cols="2"> <Card title="Mitglieder und Rollen" icon="users" href="/de/platform/admin/members-and-roles"> Die sechs Rollen und die ressourcengenaue Matrix, die sagt, wer lesen, schreiben, konfigurieren und regeln darf. </Card> <Card title="Teams" icon="users-round" href="/de/platform/admin/teams"> Gruppiere Mitglieder in Teams, die Agents, Prompts und Integrationen teilen. </Card> <Card title="Agents" icon="bot" href="/de/platform/admin/agents"> Jeder Agent, den die Organisation hat, und wo ein Admin eingreift, wenn einer Governance braucht. </Card> <Card title="KI-Anbieter" icon="cpu" href="/de/platform/admin/providers"> Verbinde die OpenAI-kompatiblen Anbieter hinter jeder Antwort und wähl, welche Modelle die Organisation nutzen darf. </Card> <Card title="Token-Quellen" icon="key-round" href="/de/platform/admin/token-sources"> Geteilte Anmeldedaten, auf die Agents und Tools zugreifen, ohne dass jedes Mitglied das Geheimnis hält. </Card> <Card title="Integrationen" icon="plug" href="/de/platform/admin/integrations"> Installiere und rotiere die Anmeldedaten hinter Slack, Gmail, Outlook, Google Drive, GitHub, Shopify und mehr. </Card> <Card title="Enterprise SSO" icon="shield-check" href="/de/platform/admin/enterprise-sso"> Verdrahte die Anmeldung mit deinem Identity-Provider über SAML oder OIDC. </Card> <Card title="API-Schlüssel" icon="key" href="/de/platform/admin/api-keys"> Erzeuge und begrenze die Schlüssel, mit denen externer Code Tales REST-API erreicht. </Card> <Card title="Branding" icon="palette" href="/de/platform/admin/branding"> Der Name, das Logo und die Farben, die der Rest der Organisation sieht. </Card> <Card title="Zwei-Faktor-Authentifizierung" icon="smartphone" href="/de/platform/admin/two-factor-authentication"> Verlange einen zweiten Faktor für die Anmeldung und verwalte die Einrichtung organisationsweit. </Card> <Card title="Changelog" icon="history" href="/de/platform/admin/changelog"> Der produktinterne Eintrag darüber, was wann ausgeliefert wurde. </Card> <Card title="Governance" icon="scale" href="/de/platform/admin/governance/audit-logs"> Audit-Logs, Richtlinien und Limits, Guardrails, Analysen, Aufbewahrung und Legal Hold. </Card> </CardGroup> ## Wo das hingehört Admin ist die Oberfläche, die jeder andere Tab voraussetzt. Chat löst ein Modell über die hier konfigurierten Anbieter auf; Agents rufen Tools über die hier konfigurierten Integrationen auf; die Prompt-Bibliothek und die Inbox respektieren die hier konfigurierten Team-Grenzen. Die natürliche erste Lektüre ist [Mitglieder und Rollen](/de/platform/admin/members-and-roles) — jede andere Admin-Seite verweist auf die Rollennamen, die sie definiert. # Changelog Source: https://tale.dev/docs/de/platform/admin/changelog Der Changelog ist der In-Produkt-Viewer, der Release Notes für die Tale-Plattform selbst anzeigt — nicht für Inhalte, die deine Mitglieder produzieren. Nach einem selbst gehosteten Upgrade oder einem Managed-Cloud-Rollout listet der Viewer auf, was sich zwischen der vorherigen Version und der jetzt laufenden geändert hat. Admins lesen ihn nach einem Upgrade, um das Team einzuweisen und alles zu markieren, was die Arbeit der Mitglieder berührt. Der Viewer liest Release Notes aus dem Tale-Repository auf GitHub und cached sie in deiner Instanz, damit die Seite auch lädt, wenn GitHub nicht erreichbar ist. ## Wo der Changelog lebt Der Changelog hat zwei Oberflächen. Die Seite **Was ist neu** unter **Hilfe** listet jeden jüngsten Release mit den vollen Notes. Der **Upgrade-Toast** feuert einmal pro Major-Versionssprung und verlinkt direkt auf die Seite — der Toast zeigt `Auf v<version> aktualisiert` und bleibt bis zum Schliessen stehen, damit ein Mitglied, das weg war, den Hinweis nicht verpasst. Öffne die Seite über das Hilfemenü in der oberen Leiste oder über den Upgrade-Toast, wenn er erscheint. Die Seite cached etwa dreissig jüngste Releases; ältere verlinken in die GitHub-Release-Historie. ## Was jeder Eintrag zeigt Jeder Release-Eintrag trägt vier Felder: das Versions-Tag, das Veröffentlichungsdatum, den Release-Namen (oft eine kurze Überschrift) und den Release-Body in Markdown. Tale rendert den Body wie GitHub — Überschriften, Listen, Links und Code-Fences überleben alle. Releases, die GitHub noch nicht veröffentlicht hat, zeigen eine kurze Erklär-Karte mit einem Link zur öffentlichen Release-Historie. ## Scope Der Changelog ist der Changelog der Plattform — was sich in Tale selbst geändert hat. Er zeigt nicht Änderungen an deinen Agents, deinen Workflows oder deiner Wissensdatenbank; die haben ihre eigene Pro-Ressource-Historie. Wenn du die Versionshistorie eines Agents oder Workflows suchst, öffne die Ressource und wechsle auf den Tab **Historie**. Der Viewer ist nur-lesend und für jedes angemeldete Mitglied sichtbar. Es gibt kein Admin-only-Flag — jeder mit einem Account kann die Seite öffnen. Die Daten, die der Viewer abruft, sind öffentliche Release-Informationen aus dem Tale-GitHub-Repository, also gibt es nichts Organisationsinternes zu verstecken. ## Ein durchgespieltes Upgrade Nach einem selbst gehosteten Upgrade von `v0.42` auf `v0.45` melde dich an und schau oben rechts nach dem Upgrade-Toast. Klick auf **Anzeigen**, um die Changelog-Seite zu öffnen. Die Seite zeigt drei Release-Einträge (`v0.43`, `v0.44`, `v0.45`), neuester zuerst, jeder mit den von Entwicklern geschriebenen Notes aus dem GitHub-Release. Geh die Highlights durch, teile den Link mit dem Team, falls etwas ein grösseres Publikum braucht, und der Toast verschwindet beim nächsten Neuladen. Wenn das Upgrade über das gecachte Fenster hinausgeht, zeigt die Seite die jüngsten Einträge mit einem Banner, der für die früheren Notes auf GitHub verlinkt. Der Cache bleibt warm für den nächsten Leser auf deiner Instanz. ## Wo das hingehört Der Changelog ist die Operator-Lesart dessen, was Tale selbst gerade getan hat; er steht neben dem Audit-Log (das festhält, was deine Mitglieder getan haben) und der Anbieter-Seite (die festhält, welche Modellversionen verdrahtet sind). Paar ihn mit [Selbst gehostetes Upgrade](/de/self-hosted/operate/upgrades), wenn du die Instanz betreibst — der Upgrade-Leitfaden geht den Versionssprung durch, und der Changelog liest auf der anderen Seite das Ergebnis aus. # Branding Source: https://tale.dev/docs/de/platform/admin/branding Branding ist die Oberfläche, die Tales Standard-Chrome gegen die deiner Organisation tauscht. Die Seite deckt die Assets ab, die die Plattform überzieht — Logo, Favicon und die Akzentfarbe, aus der sich die Palette ableitet — und erklärt, wo jedes davon erscheint, damit du vor dem Speichern eine Vorschau hast. Der Produktname selbst folgt automatisch dem Namen deiner Organisation, es gibt also kein separates Feld dafür. Admins greifen zu Branding, wenn eine selbst gehostete Instanz an ein externes Publikum geht oder wenn ein internes Rollout sich nativ für die Firma anfühlen soll. Nur Admins und Inhaber können Branding bearbeiten. Alle anderen sehen das Ergebnis; das Formular selbst ist für Redakteure, Entwickler und Mitglieder ausgeblendet. <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.](/images/platform/settings-branding.webp) </Frame> ## Wo Branding lebt Öffne **Einstellungen > Branding**. Das Formular hat drei Abschnitte (Logo-Upload, Favicon-Upload, Akzentfarbe) und eine Live-Vorschau, die die Sidebar mit den Werten spiegelt, die du gerade bearbeitest. Speichern setzt die Änderung beim nächsten Seitenaufruf für jedes Mitglied _dieser_ Organisation um — eine Pro-Benutzer-Überschreibung gibt es nicht. Branding ist auf eine Organisation beschränkt. Jede Organisation behält ihr eigenes Logo, Favicon und ihre Akzentfarbe, sodass ein Wechsel der Organisation die Chrome auf das Branding dieser Organisation umstellt, statt das der vorherigen mitzunehmen. Bearbeitungen hier ändern nur die Organisation, in der du dich gerade befindest. ## Der Produktname Es gibt kein Feld für „App-Name" oder „Text-Logo". Die Wortmarke im Sidebar-Kopf und der Name im Browser-Tab-Titel sind der eigene Name deiner Organisation, den du auf der Seite **Einstellungen > Organisation** setzt. Benenn die Organisation um, und die Chrome folgt beim nächsten Seitenaufruf. Lade ein Logo-Bild hoch (siehe unten), und es nimmt den Platz der Wortmarke ein; ohne Logo wird der Organisationsname als Text-Wortmarke gerendert. ## Die Assets **Logo** ist ein Bild — PNG, SVG oder JPG. Die Plattform rendert es in Sidebar-Höhe; ziel auf transparenten Hintergrund und eine Wortmarke, die bei etwa 32 Pixel Höhe lesbar ist. Das Logo ist ein einzelner Upload für beide Themes — wähl eine Marke, die auf hellem wie dunklem Hintergrund lesbar ist. Ohne Logo fällt die Chrome auf den Namen deiner Organisation als Text-Wortmarke zurück. **Favicon** ist das Tab-Icon. Lade eine helle und eine dunkle Variante hoch, damit das Icon lesbar bleibt, egal welches Theme das Betriebssystem gewählt hat — oder lass es leer, und Tale leitet eines aus deinem Logo ab, sobald du es hochlädst, sodass ein einziger Upload sowohl die Sidebar als auch den Browser-Tab überzieht. Ein explizit gesetztes Favicon gewinnt immer gegen das automatisch abgeleitete. **Akzentfarbe** ist die eine Farbe, aus der sich die Marken-Palette ableitet — Buttons, Fokusringe, Auswahlzustände und die aktive Zeile in der Sidebar nehmen ihren Ton von ihr. Sie akzeptiert jeden Hex-Wert, einmal gewählt für hell wie dunkel; Tale leitet pro Theme eine lesbare Palette ab — wäre die gewählte Farbe gegen den Hintergrund eines Themes schwer lesbar, wird sie nur für dieses Theme in den Kontrast geschoben, das andere bleibt unangetastet, und dieselbe Marke liest sich auf beiden sauber. Die Vorschau zeigt die abgeleitete Palette für das Theme, das du gerade ansiehst. ## Ein durchgespieltes Rebranding Um eine Instanz für `Acme Corp` umzubranden, setz zuerst den Namen der Organisation auf `Acme Corp` auf der Seite **Einstellungen > Organisation** — dieser Name wird zur Sidebar-Wortmarke und zum Browser-Tab-Titel. Öffne dann **Einstellungen > Branding**, lade die Firmen-Wortmarke als Logo hoch und füge den Marken-Hex (`#3B82F6` im Beispiel) ins Feld für die Akzentfarbe ein. Lass das Favicon leer, und Tale erzeugt eines aus dem Logo. Das Vorschaufeld rechts aktualisiert sich, während du tippst. Speichern setzt die Änderung um; die Sidebar, der Browser-Tab und das Favicon spiegeln das neue Branding sofort. ## Der eigene Login-Screen Die Anmelde-, Registrierungs- und Passwort-Reset-Screens werden gerendert, bevor du eine Organisation gewählt hast — es gibt also keine Organisation im Kontext, mit der sie gebrandet werden könnten. Sie zeigen das Standard-Branding der Plattform statt das einer einzelnen Organisation; das Branding pro Organisation übernimmt, sobald du im Arbeitsbereich dieser Organisation landest. Melde dich ab und lade die Login-URL neu, um zu prüfen, welche Assets die Pre-Auth-Screens verwenden. ## Wo das hingehört Branding ist die visuelle Schicht über jeder anderen Admin-Oberfläche; SSO, E-Mail und Audit-Logs tragen die gebrandete Chrome zu deinen Mitgliedern. Weil der Produktname der eigene Name der Organisation ist, halt ihn bei [Mitglieder und Rollen](/de/platform/admin/members-and-roles) scharf. Paar Branding mit [Anbieter](/de/platform/admin/providers), damit die Modellnamen im Chat-Header zur Chrome drumherum passen, und mit [Mitglieder und Rollen](/de/platform/admin/members-and-roles), damit die Personen, die Branding bearbeiten dürfen, dieselben sind, denen der Rest der Org-Chrome gehört. # Richtlinien und Limits Source: https://tale.dev/docs/de/platform/admin/governance/policies-and-limits Richtlinien und Limits ist die Oberfläche, auf der du deckelst, was deine Mitglieder und Agents verbrauchen können. Budgets deckeln Tokens, Kosten und Anfragen pro Abrechnungsperiode; Feature-Kontrollen schalten Web-Suche, Code-Ausführung und Datei-Upload pro Bereich um; Upload-Richtlinie regelt Dateitypen und Größen, die ein Mitglied anhängen darf; Aufbewahrungsrichtlinie entscheidet, wie lange jeder Datentyp lebt, bevor Cleanup eingreift. Admins und Inhaber lesen diese Seite, wenn eine Last über Budget ist, wenn ein Feature für eine Untermenge von Benutzern aus sein soll, oder wenn ein Regulierer ein Aufbewahrungsfenster benennt, das vom Default abweicht. <Frame caption="Governance > Richtlinien & Limits — die Tabelle der Budget-Regeln über der Upload-Richtlinie und den Aufbewahrungs-Kontrollen."> ![Die Governance-Seite Richtlinien und Limits zeigt drei monatliche Budget-Regeln — eine für die gesamte Organisation, eine als Default für alle Benutzer und eine für die Rolle developer, jede mit Obergrenzen für Tokens, Kosten und Anfragen — über den Feldern der Upload-Richtlinie für erlaubte Dateitypen, Größen und Volumen.](/images/platform/governance-policies-limits.webp) </Frame> ## Ein durchgespieltes Budget Um die monatlichen Ausgaben eines Redakteurs zu deckeln, öffne **Einstellungen > Richtlinien > Budgets** und klick auf **Regel hinzufügen**. Wähle **Rolle** als Bereich, **Redakteur** als Ziel, setze die Periode auf **Monatlich** und trage einen Höchstbetrag in USD ein. Speichern, und die nächste Monats-Periode-Anfrage, die einen Redakteur über das Limit drücken würde, wird mit einem Budget-überschritten-Fehler abgelehnt. Eine Warnschwelle unter dem Limit löst eine Warnung aus, bevor das Limit erreicht wird. Engere Bereiche übersteuern weitere — eine Benutzerregel schlägt eine Team-Regel schlägt eine Rollen-Regel — und org-weite Limits wirken immer zusätzlich obendrauf. ## Die vier Richtlinienebenen **Budgets** sind Token-, Kosten- und Anfragen-Limits pro Bereich und Periode. Bereiche sind Organisation, Rolle, Team, Benutzer oder API-Schlüssel. Jede Regel trägt ein Token-Limit, ein Kosten-Limit in USD, ein optionales Anfragen-Limit und eine Warnschwelle als Prozentwert des Limits. Eine API-Schlüssel-Regel zielt auf einen einzelnen ausgestellten Schlüssel (wähle **API-Schlüssel** als Bereich, dann den Schlüssel aus **Einstellungen > API**) und deckelt nur den mit diesem Schlüssel authentifizierten Traffic — die REST- und OpenAI-kompatible API — sodass du eine einzelne Integration messen kannst, ohne die In-App-Nutzung zu berühren. Bildgenerierung wird nach Kosten und Anzahl Anfragen gemessen, nicht nach Tokens — eine Bild-Anfrage meldet keine Tokens, also deckle Bild-Ausgaben mit dem Kosten- oder Anfragen-Limit, nicht mit dem Token-Limit. **Feature-Kontrollen** schalten Web-Suche, Code-Ausführung und Datei-Upload pro Bereich um und deckeln die maximalen Kontext-Tokens für AI-Antworten. Ein Feature, das für einen Bereich aus ist, blendet die Schaltfläche im Chat aus und lehnt die Anfrage serverseitig ab. **Upload-Richtlinie** regelt Dateierweiterungen, MIME-Typen und Größen, die ein Mitglied anhängen darf. Sie deckelt zudem das Gesamtvolumen pro Benutzer — nützlich, wenn Speicher gemessen wird. Schalte die Richtlinie aus für einen permissiven Default; schalte sie ein, um die Listen durchzusetzen. **Aufbewahrungsrichtlinie** entscheidet, wie lange jeder Datentyp (Chatverlauf, Dokumente, Prompts, Audit-Logs, Nutzungsbuch, Workflow-Läufe und mehr) bleibt, bevor der Cleanup-Lauf die Zeile entfernt. Die Seite zeigt die vom Betreiber gesetzten Grenzen, die Per-Org-Überschreibung innerhalb dieser Grenzen und ein Kulanzfenster vor der harten Löschung. ## Vorrang Alle vier Ebenen teilen sich dieselbe Bereichsleiter: Benutzer > Team > Rolle > Organisation > Default. Die engste Regel gewinnt. Wo eine Ebene ein org-weites Limit trägt (Budgets), wirkt das Limit als zusätzliche Decke über jeder engeren Regel. Ein API-Schlüssel-Budget steht außerhalb der Leiter als eigener, unabhängiger Topf: Es bindet den Traffic des Schlüssels selbst, unabhängig von den Benutzer-, Team- oder Org-Limits des Inhabers, sodass ein einzelner Schlüssel enger gedeckelt werden kann als die Person, die ihn ausgestellt hat. ## Aufbewahrungs-Grenzen und Freigaben Die Aufbewahrungsrichtlinie sitzt innerhalb von Grenzen, die der Betreiber gesetzt hat — der Selbsthosting-Betreiber setzt eine Untergrenze und eine Obergrenze pro Kategorie, und der Org-Wert klemmt auf diesen Bereich. Wenn der Betreiber eine engere Untergrenze oder eine niedrigere Obergrenze vorschlägt, erscheint die Änderung als Vorschlag, den Admins anwenden oder ablehnen können. Reduzierungen der Richtlinie landen mit einem Pending-Banner und einem Kulanzfenster, bevor sie wirken — dieselbe Kulanz gibt Admins die Möglichkeit, abzubrechen. ## Sitzungs-Leerlaufzeit Die Sitzungs-Leerlaufzeit meldet Mitglieder nach einer Phase der Inaktivität ab — die sitzungsgebundene Kontrolle, die Compliance-Rahmenwerke verlangen (SOC 2 CC6.1). Öffne **Einstellungen > Richtlinien > Sicherheit & Überwachung**, schalte **Sitzungs-Leerlaufzeit aktivieren** ein und setze **Leerlaufzeit (Minuten)** (1–1440, Standard 30). Mitglieder sehen kurz vor dem Ablauf eine Warnung; danach meldet sich der aktive Tab ab, und die Anmeldeseite erklärt die Abmeldung, statt nur ein leeres Formular zu zeigen. Das Fenster kann das installationsweite Limit nur verkürzen, niemals verlängern. Selbsthosting-Betreiber setzen diese harte Obergrenze per Umgebungsvariable (siehe die [Umgebungsreferenz](/de/self-hosted/configuration/environment-reference)); die Org-Richtlinie wirkt obendrauf, und das engere der beiden Fenster gewinnt. Ein Mitglied mehrerer Organisationen bekommt das engste Fenster über alle seine Organisationen. Die Durchsetzung hat zwei Hälften. Der Watchdog im Browser beendet offene, sichtbare Sitzungen auf die Minute. Geschlossene Tabs und liegen gelassene Geräte fängt serverseitig ein Widerrufs-Lauf ab, der etwa alle fünf Minuten läuft — eine Sitzung kann das Fenster also um einige Minuten überleben; wenn du die Kontrolle gegenüber einem Auditor benennst, rechne mit dem Fenster plus rund einer halben Stunde im schlechtesten Fall. Jeder serverseitige Widerruf landet als `session.idle_revoked` in den [Audit-Logs](/de/platform/admin/governance/audit-logs). Eine Einschränkung für Trusted-Headers-Deployments: dort besitzt der Reverse Proxy die Authentifizierung, eine widerrufene Sitzung entsteht also neu, sobald das Mitglied den Anmelde-Hinweis bestätigt — kombiniere die Richtlinie mit einer Leerlaufzeit auf Proxy- oder IdP-Seite für eine echte Sperre. ## Wo das hingehört Richtlinien und Limits ist die Budget- und Schleusen-Ebene, die die Organisation vor entgleitenden Ausgaben und unbeabsichtigtem Zugriff schützt. Paare das mit [Inhalte und Modelle](/de/platform/admin/governance/content-models), sodass das vom Budget gedeckelte Modell auch das ist, das die Zugriffsliste erlaubt, und mit [Aufbewahrungsrichtlinie auf derselben Seite](#aufbewahrungs-grenzen-und-freigaben), sodass die Daten, die die Organisation behält, ebenfalls begrenzt sind. Die Begleitseite ist [Audit-Logs](/de/platform/admin/governance/audit-logs) — jede Richtlinienänderung hier landet dort als dauerhafte Aufzeichnung. # Run-code-Richtlinie Source: https://tale.dev/docs/de/platform/admin/governance/run-code-policy Run-code-Richtlinie ist die Oberfläche, auf der du entscheidest, welche Python- und Node-Pakete die Sandbox zur Laufzeit installieren kann. Skills mit Skripten und das Run-code-Tool laufen beide in derselben Sandbox; diese Richtlinie ist die einzige Naht, an der du anziehst oder lockerst, was sie installieren dürfen. Admins und Inhaber lesen diese Seite, wenn ein Agent eine neue Bibliothek braucht oder wenn ein Audit fragt, warum ein Paket zu einem bestimmten Zeitpunkt blockiert war. <Frame caption="Governance > Run-code-Pakete — die Radiogruppe für den Standardmodus über den Zulassungs- und Sperrlisten für Python und Node."> ![Die Governance-Seite Run-code-Richtlinie mit Zulassungsliste als gewähltem Standardmodus, darunter eine Python-Zulassungsliste mit pandas, numpy, scipy und scikit-learn, eine Python-Sperrliste mit paramiko, fabric, pexpect und scapy sowie eine Node-Zulassungsliste mit axios, date-fns, dayjs und lodash.](/images/platform/governance-run-code-policy.webp) </Frame> ## Ein durchgespielter Wechsel Der Standardmodus ist **Sperrliste** mit leerer Liste, was bedeutet, dass jedes Paket installierbar ist. Um auf eine kuratierte Menge zu wechseln, öffne **Einstellungen > Richtlinien > Run-code-Pakete**, ändere den Modus auf **Zulassungsliste** und liste die Pakete unter **Python-Zulassungsliste** und **Node-Zulassungsliste** auf, denen du vertraust. Speichern, und der nächste Sandbox-Lauf, der ein Paket außerhalb der Liste anfordert, scheitert mit dem Grund **nicht auf der Zulassungsliste** im Audit-Ereignis. ## Die zwei Modi | Name | Default | Beschreibung | | --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Zulassungsliste | aus | Nur die aufgelisteten Pakete installieren; alles andere wird abgelehnt. Nutz das, wenn ein Regulierer die freigegebenen Bibliotheken benennt. | | Sperrliste | an | Jedes Paket installiert außer den aufgelisteten. Nutz das, wenn eine kleine Menge als schlecht bekannt ist und der Rest vertraut wird. | ## Die vier Listen Jeder Modus liest aus zwei Listen — Python und Node. Ein Paket pro Zeile oder kommagetrennt. Versionsangaben werden automatisch entfernt (`pandas==2.1` entspricht `pandas`), sodass die Richtlinie namensbasiert ist und Bibliotheks-Upgrades übersteht. Scoped Node-Pakete (`@scope/pkg`) werden unterstützt. Die Listen sind pro Sprache unabhängig: eine Python-Zulassungsliste plus eine Node-Sperrliste ist eine gültige Kombination und bedeutet, dass Python streng ist und Node permissiv auf derselben Sandbox. ## Der Tester Das Test-Panel auf derselben Seite erlaubt dir, pip- oder npm-Spezifikationen einzufügen und zu sehen, ob jede unter dem aktuellen Entwurf durchgehen würde. Es verwendet deine ungespeicherten Änderungen, sodass du vor dem Speichern iterieren kannst. Jede Spezifikation wird geparst, von ihrer Versionsangabe befreit und gegen die Listen abgeglichen; das Panel meldet **Erlaubt** oder **Abgelehnt** mit der Begründung — passt-zur-Zulassungsliste, nicht-auf-der-Zulassungsliste, passt-zur-Sperrliste, nicht-auf-der-Sperrliste. ## Netzwerk-Egress und Skills Die Paket-Richtlinie regelt, _was_ in der Sandbox läuft. Dieselbe Sandbox läuft Skill-Skripte — siehe die [Skills-Konzeptseite](/de/platform/agents/skills). Ausgehendes Netzwerk aus Sandbox-Code ist standardmäßig offen, Cloud-Metadaten und private Adressbereiche sind immer blockiert; bei selbst gehosteten Deployments kann der Operator es auf Deployment-Ebene auf eine Hostname-Zulassungsliste einschränken — die Anleitung steht in [Hardening](/de/self-hosted/operate/security/hardening). Behandle das Veröffentlichen eines Skills mit Skript als Erweiterung der Vertrauensfläche für jeden Agent, der es aufnimmt; die Paket-Richtlinie und die Egress-Richtlinie des Deployments entscheiden zusammen, was das Skript tun darf. ## Wo das hingehört Run-code-Richtlinie ist die Schleuse auf der Sandbox, die sowohl das Run-code-Tool als auch Skill-Skripte trägt. Das begleitende Konzept ist [Agent-Skills](/de/platform/agents/skills) — es deckt ab, wann ein Skript als Skill veröffentlicht wird und warum die Paket-Richtlinie die tragende Schleuse ist. Die begleitende Governance-Seite ist [Audit-Logs](/de/platform/admin/governance/audit-logs) — jede abgelehnte Paket-Installation landet dort mit der Spezifikation und der Begründung. # Inhalte und Modelle Source: https://tale.dev/docs/de/platform/admin/governance/content-models Inhalte und Modelle ist die Oberfläche, auf der du entscheidest, welche LLMs die Personen in deiner Organisation erreichen können und auf welchem jede Gruppe per Default landet. Sie verbindet eine Zulassungs- oder Sperrliste pro Bereich (Organisation, Team, Rolle, Benutzer) mit einer Default-Modell-Regel, die der Resolver anwendet, wenn weder ein Agent noch eine Konversation die Wahl überschrieben hat. Admins und Inhaber lesen diese Seite, wenn eine Compliance-Regel eine Last an ein freigegebenes Modell bindet, wenn ein Team auf einem günstigeren Modell als der Rest der Organisation landen soll, oder wenn ein neues Modell eines bestehenden Anbieters erreichbar gemacht werden muss. <Frame caption="Governance > Inhalte & Modelle — der verpflichtende System-Prompt-Präfix und -Suffix über den Default-Modell-Regeln pro Bereich."> ![Die Governance-Seite Inhalte und Modelle zeigt die Felder für den verpflichtenden System-Prompt-Präfix und -Suffix, gefüllt mit den Hausregeln der Organisation, über einer Tabelle mit drei Default-Modell-Regeln — einem Default für alle Benutzer und je einer Rollen-Regel für Entwickler und Mitglied, jede auf ein OpenRouter-Modell festgelegt.](/images/platform/governance-content-models.webp) </Frame> ## Ein durchgespielter Default Um das Default-Modell für die Redakteur-Rolle zu setzen, öffne **Einstellungen > Richtlinien > Standardmodelle** und klick auf **Regel hinzufügen**. Wähle **Rolle** als Bereich, **Redakteur** als Ziel, dann wähle den Anbieter und das Modell. Speichern, und die nächste Anfrage eines Redakteurs ohne expliziten Per-Agent- oder Per-Konversations-Override landet auf dem Modell der Regel. Engere Bereiche gewinnen — eine Benutzerregel schlägt eine Team-Regel schlägt eine Rollen-Regel schlägt den Org-Default. ## Die zwei Ebenen **Modellzugriff** ist die Zulassungs- oder Sperrliste, die regelt, welche Modelle ein Bereich überhaupt nutzen darf. Ein Modell, das nicht auf der Zulassungsliste steht, ist für diesen Bereich unsichtbar — die Auswahl blendet es aus und der Resolver weigert sich, daran zu binden, selbst wenn ein Agent es gepinnt hat. Greif zur Zulassungsliste, wenn ein Regulierer die freigegebenen Modelle benennt; greif zur Sperrliste, wenn ein einzelnes Modell überall sonst nicht erreichbar sein soll. **Standardmodelle** ist die Resolver-Regel, die das Modell auswählt, wenn nichts anderes es getan hat — kein Per-Agent-Override, kein Per-Konversations-Override. Der Default wirkt in dem Moment, in dem der Benutzer einen frischen Chat startet, und wirkt als Fallback, wenn das gepinnte Modell eines Agents nicht erreichbar ist. ## Bereiche und Vorrang Beide Ebenen tragen einen Bereich: Organisation, Team, Rolle oder Benutzer. Der Resolver wertet von eng nach weit aus — Benutzer schlägt Team schlägt Rolle schlägt Org-Default. Die Modellzugriffs-Ebene kombiniert mit der Default-Modell-Ebene; der Default, den der Resolver wählt, muss auch die Zugriffsprüfung für denselben Bereich bestehen, andernfalls fällt der Resolver auf das nächste erlaubte Modell zurück. ## Zulassungs- und Sperrlisten-Warnungen Der Default-Modell-Editor zeigt eine Warnung, wenn eine Regel ein Modell nennt, das die Zulassungsliste für denselben Bereich nicht erlaubt, oder wenn die Sperrliste für denselben Bereich es blockiert. Die Warnung blockiert das Speichern nicht — der Resolver wird zur Anfragezeit zurückfallen — aber sie markiert die Diskrepanz, damit du das eine oder das andere korrigieren kannst. ## Wo das hingehört Inhalte und Modelle ist die Schleuse, die jeder Chat und jeder Agent zur Anfragezeit durchläuft. Modellzugriff mit Standardmodellen zu kombinieren erlaubt dir, eine enge Compliance-Haltung auszuliefern, ohne jedem Agent-Autor das Modell aufzuzwingen, das in diesem Quartal genehmigt ist. Die Begleitseite ist [Richtlinien und Limits](/de/platform/admin/governance/policies-and-limits) — sie deckt die Kosten- und Anfragen-Limits ab, die zusätzlich zu den hier getroffenen Modellwahlen gelten. # Guardrails Source: https://tale.dev/docs/de/platform/admin/governance/guardrails Guardrails ist die Oberfläche, auf der du die drei Filterebenen konfigurierst, die Tale auf jede Chat-Nachricht in deiner Organisation anwendet. Jede Nachricht durchläuft Inhaltssicherheit (Wortlisten und Admin-Regex), dann PII-Erkennung (eingebaute Muster plus eigene), dann einen optionalen externen Moderationsanbieter — in dieser festen Reihenfolge, auf dem Weg hinein und auf dem Weg hinaus. Admins und Inhaber lesen diese Seite, wenn ein Regulierer eine Inhaltsregel benennt, wenn ein Leck eine strengere Richtlinie rechtfertigt, oder wenn die Antworten eines Agents bereinigt werden müssen, bevor sie das Modell verlassen. <Frame caption="Governance > Guardrails — die drei Status-Karten der Filterebenen (Inhaltssicherheit, PII-Erkennung, Moderationsanbieter) über dem Log der letzten Ereignisse."> ![Die Governance-Seite Guardrails zeigt drei Status-Karten — Inhaltssicherheit greift auf Ein- und Ausgabe über zwei Kategorien, die PII-Erkennung läuft im Modus mask über vier eingebaute Muster, und der Moderationsanbieter steht auf Deaktiviert, ohne konfigurierte externe API — über dem Feed der letzten Ereignisse, der noch keine Ereignisse meldet.](/images/platform/governance-guardrails.webp) </Frame> ## Eine durchgespielte Schichtung Um die Ebenen zu konfigurieren, öffne **Einstellungen > Richtlinien > Guardrails**. Die Übersicht zeigt drei Status-Karten, eine pro Ebene — Inhaltssicherheit, PII-Erkennung, Moderation. Jede Karte verlinkt auf ihre eigene Konfigurationsseite, auf der du wählst, ob die Ebene auf Eingaben, Ausgaben oder beidem läuft und was sie bei einem Treffer tut (Nachricht blockieren, Treffer maskieren oder markieren und durchlassen). Die Tabelle der letzten Ereignisse unten in der Übersicht zeigt die letzten 50 Erkennungen, Blockaden und Anbieter-Fehler mit ihrer Ebene, ihrer Richtung und ihrer Treffer-Kategorie. ## Inhaltssicherheit Inhaltssicherheit ist die Ebene, die du selbst besitzt. Definiere eine oder mehrere Kategorien — Hassrede, Profanität, eine eigene Regex für einen internen Codenamen — und wähle einen Modus pro Kategorie: **Blockieren** lehnt die Nachricht ab, **Maskieren** ersetzt Treffer durch einen Platzhalter, **Markieren** vermerkt die Erkennung, ohne die Nachricht zu ändern. Blockieren schlägt Maskieren schlägt Markieren, wenn mehr als eine Kategorie greift. Die Wortlisten und Muster dieser Ebene verlassen das Deployment nie. Getroffener Text wird nicht gespeichert — nur die Kategorie, die Richtung (Eingabe oder Ausgabe) und die Trefferanzahl landen im Audit-Ereignis. ## PII-Erkennung PII-Erkennung bringt Muster für E-Mails, Telefonnummern, Behörden-IDs, Zahlungsnummern und eine lange Liste regionaler Formate mit. Füge eigene Muster hinzu, wenn dein Regulierer ein Format benennt, das die eingebauten verfehlen. Wähle einen Modus — Blockieren, Maskieren mit einem Platzhalter, oder Markieren — und eine Anwendungsrichtung. Maskieren ist die typische Wahl für die Ausgabefilterung, wenn das Modell Zugriff auf Datensätze mit PII bekommen hat, die es nicht zurückspielen soll. ## Moderationsanbieter Die Moderationsebene ist ein externer Klassifikator — OpenAI Moderation, Azure Content Safety, Perspective API oder ein eigener HTTP-Endpunkt. Konfiguriere den Endpunkt des Anbieters, einen API-Key und das Kategorie-zu-Aktion-Mapping (jeder Anbieter liefert seine eigene Taxonomie zurück; das Mapping entscheidet, welche Kategorien blockieren, maskieren oder markieren). Die Ebene ist optional — lass sie deaktiviert und nur die ersten zwei Ebenen laufen. Der Anbieter sitzt auf dem Egress-Netzwerkpfad. Ausfälle sind pro Richtung konfigurierbar: Fail-open lässt die Nachricht durch, Fail-closed lehnt sie ab. Die Ansicht der letzten Ereignisse zeigt Anbieter-Fehler, HTTP-Statuscodes und Circuit-Open-Ereignisse, wenn die Ebene gerate-limited ist. ## Letzte Ereignisse Jede Erkennung, Blockade und jeder Anbieter-Fehler landet 30 Tage lang in der Tabelle der letzten Ereignisse. Filtere nach Ebene oder nach Art; klick auf eine Zeile, um die getroffenen Kategorien, den Akteur, die Nachrichten-ID und den Zeitstempel zu sehen. Getroffener Roh-Text wird nie gespeichert — die Ereignisse sind eine Tuning-Oberfläche, kein Inhalts-Archiv. ## Wo das hingehört Guardrails ist der Laufzeit-Filter zwischen Benutzer und Modell in beide Richtungen. Paare das mit [Inhalte und Modelle](/de/platform/admin/governance/content-models), sodass ein freigegebenes Modell auch den freigegebenen Inhaltsregeln unterliegt. Die Begleitseite ist das [Audit-Log](/de/platform/admin/governance/audit-logs) — jede Blockade und jede Maskierung der Guardrail-Ebenen landet dort als dauerhafte Aufzeichnung. # Nutzungs-Analyse Source: https://tale.dev/docs/de/platform/admin/governance/usage-analytics Nutzungs-Analyse ist das Dashboard, das jeden abrechenbaren AI-Aufruf in einer einzigen Ansicht von Tokens, Kosten und Anfragenvolumen aggregiert. Es schneidet nach Benutzer, Team, Rolle, Modell, Agent und Zeit, sodass die unerwartete Zeile auf der Rechnung zur Last zurückführbar ist, die sie verursacht hat. Admins und Inhaber lesen diese Seite, wenn eine Rechnung unerwartet ist, wenn die Führung die grobe Form der AI-Ausgaben will, oder wenn eine Budgetwarnung auslöst und die nächste Frage _wer und was_ ist. ## Eine durchgespielte Detailansicht Öffne **Einstellungen > Richtlinien > Nutzung**. Die Default-Ansicht sind die letzten 30 Tage, org-weit, mit den drei Kennzahlen-Zählern — Tokens insgesamt, Kosten insgesamt in USD, Anfragen insgesamt. Wechsle die Aufschlüsselung auf **Nach Benutzer**, um die größten Verbraucher zu finden, **Nach Modell**, um ein teures Primärmodell mit einem günstigeren Fallback zu vergleichen, oder **Nach Agent**, um den Agent zu finden, der die Last treibt. Jede Zeile öffnet eine Per-Zeile-Zeitreihe; die Diagrammachse folgt der gewählten Periode. ## Die Dimensionen - **Benutzer** — jedes Mitglied, das einen abrechenbaren Aufruf ausgelöst hat. Paare mit dem Team- oder Rollenfilter, um die Ansicht einzugrenzen. - **Team** — aggregiert über Team-Mitglieder; nützlich, wenn Budgets team-gebunden sind. - **Rolle** — Inhaber, Admin, Entwickler, Redakteur, Mitglied. - **Modell** — jedes Modell, das eine Antwort erzeugt hat, gruppiert nach Anbieter. - **Agent** — jeder benannte Agent (die Rangliste sortiert nach Token-Volumen, Kosten oder Anfragenzahl). - **Zeit** — täglicher Trend für kurze Fenster, wöchentlich für längere. ## Das Kostenmodell Kosten sind eine Schätzung. Jede Anfrage landet im Nutzungsbuch mit Eingabe-Tokens, Ausgabe-Tokens, dem veröffentlichten Preis des Modells pro Million Tokens und der Wanduhr-Dauer. Das Dashboard multipliziert Tokens mit Preis; Bildgenerierungsaufrufe landen mit einem Per-Bild-Preis, den der Anbieter zurückgibt. Die Zeile im Nutzungsbuch ist die Quelle der Wahrheit, und das [Audit-Log](/de/platform/admin/governance/audit-logs) trägt Akteur und Zeitstempel der Zeile für den Quervergleich. ## Budget-Überlagerungen Wenn [Richtlinien und Limits](/de/platform/admin/governance/policies-and-limits) ein Budget für einen Bereich hat, überlagert das Nutzungs-Diagramm das Limit als horizontale Linie. Beim Hovern auf einen Punkt erscheint der verbrauchte Anteil des Limits und der projizierte Monatsendwert basierend auf dem aktuellen Trend. Das Überschreiten der Warnschwelle färbt die Reihe orange; das Überschreiten des Limits färbt sie rot und zeigt die Budget-überschritten-Ereignisse als Marker auf der Zeitachse. ## Aufbewahrung von Nutzungs-Zeilen Das Nutzungsbuch hat sein eigenes Aufbewahrungsfenster in [Richtlinien und Limits](/de/platform/admin/governance/policies-and-limits). Default sind 365 Tage; kürze es und der historische Chart wird entsprechend gekürzt. Das Dashboard spiegelt, was das Nutzungsbuch hält — es gibt keine Archiv-Ebene darunter. ## Wo das hingehört Nutzungs-Analyse ist die Ausgaben- und Volumen-Seite derselben Last, die [Feedback-Analyse](/de/platform/admin/governance/feedback-analytics) für Qualität liest. Zusammen beantworten sie _ist dieser Agent seine Kosten wert_. Die Begleitseite ist [Richtlinien und Limits](/de/platform/admin/governance/policies-and-limits) — die Seite, auf der die Budgets, die dieses Dashboard überlagert, konfiguriert werden. # Legal Hold Source: https://tale.dev/docs/de/platform/admin/governance/legal-hold Legal Hold ist der Mechanismus, den Tale für die Beweissicherung unter Rechtshalt ausliefert. Ein Hold heftet ein Ziel — einen Benutzer, ein Dokument, einen Thread, eine Workflow-Ausführung oder die gesamte Organisation — außer Reichweite des Aufbewahrungs-Sweeps und der Löschungs-Kaskade für betroffene Personen. Admins und Inhaber lesen diese Seite, wenn der Rechtsbeistand bittet, die Daten einer Custodian-Person zu sichern, wenn ein Freigabeantrag die Vier-Augen-Freigabe braucht, oder wenn ein Audit abgleicht, welche Holds zu einem gegebenen Datum in Kraft waren. <Frame caption="Governance > Legal Hold — die Tabelle der aktiven Holds mit der Aktion Legal Hold setzen über der vier-Augen-kontrollierten Warteschlange der Freigabeanträge."> ![Die Governance-Seite 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.](/images/platform/governance-legal-hold.webp) </Frame> ## Eine durchgespielte Platzierung Um einen Hold auf einen Benutzer zu setzen, öffne **Einstellungen > Richtlinien > Legal Hold** und klick auf **Legal Hold setzen**. Wähle den Zieltyp — Benutzer, Thread, Dokument, Ausführung oder Organisation — wähle das konkrete Ziel, füge einen Grund hinzu und verknüpfe den Hold mit einem Fall, falls einer offen ist. Der Hold wirkt sofort; Aufbewahrungs-Sweeps überspringen die Zeilen des Ziels, die Löschungs-Kaskade meldet sie als **Durch Legal Hold übersprungen**, und die Zielzeile trägt das Badge **Unter Legal Hold** in jeder Liste, in der sie erscheint. ## Die vier Bereiche **Aktive Holds** ist die Arbeitsliste jedes Holds, der gerade in Kraft ist. Jede Zeile trägt den Typ, das Ziel, den Grund, den Fall, wer ihn gesetzt hat und wann. Filtere nach Typ oder nach Fall, um die Ansicht einzugrenzen. **Freigabeanträge** ist die Vier-Augen-Warteschlange. Einen Hold freigeben verlangt, dass ein anderer Admin die Anfrage genehmigt; genehmigte Anfragen warten zusätzlich eine Abkühlphase ab, bevor sie wirken. Der Bereich teilt sich in _wartet auf Freigabe_ und _genehmigt, wartet auf Abkühlphase_, sodass die Warteschlange und der Timer beide sichtbar sind. **Fälle** gruppiert Holds nach Fall. Jeder Fall trägt einen Namen, eine Fallnummer und die Liste der verknüpften Holds. Einen Fall zu schließen reicht Freigabeanträge für jeden verknüpften Hold ein — weiterhin unter Vier-Augen-Genehmigung pro Antrag. **Freigabeverlauf** ist das nur-lesbare Audit der effektiven und abgelehnten Freigaben. Nutz es, um gegen ein Beweissicherungsschreiben der Gegenseite abzugleichen oder einen Audit-Bericht zu speisen. ## Hold-und-Kaskade-Interaktion Ein Hold blockiert jeden Aufbewahrungs-Lauf und jeden Löschungs-Schritt für das Ziel. Die Papierkorb-Seite zeigt den Banner **Löschen ist durch einen aktiven Legal Hold gesperrt**, wenn ein Admin versucht, eine Zeile unter Hold zu entfernen. Eine Anfrage einer betroffenen Person, deren Subjekt von einem Hold abgedeckt ist, landet im Status **Blockiert**, bis der Hold freigegeben ist; teilweise Abdeckung (manche Threads unter Hold, manche nicht) landet in **Teilweise** mit Per-Kategorie-Zählern im Beleg. ## Vier-Augen-Kontrolle Platzieren und Freigeben sind nicht symmetrisch. Platzieren ist eine Aktion durch einen Admin allein — die Geschwindigkeit zählt, wenn Rechtsstreit kommt. Freigeben ist vier-Augen-kontrolliert: der anfordernde Admin reicht ein, ein anderer Admin gibt frei, und zwischen Genehmigung und Wirkung gilt eine Abkühlphase, sodass eine voreilige Freigabe noch abgebrochen werden kann. Beide Hälften des Workflows werden Ende zu Ende auditiert. ## Wo das hingehört Legal Hold ist der Einfrier-Knopf auf der Aufbewahrung. Er ist der einzige Mechanismus, der den zeitgesteuerten Aufbewahrungs-Sweep und die Löschungs-Kaskade für betroffene Personen schlägt — beide respektieren Holds per Konstruktion. Die Begleitseiten sind [Anfragen betroffener Personen](/de/platform/admin/governance/data-subject-requests) für die Kaskaden-Seite und [Richtlinien und Limits](/de/platform/admin/governance/policies-and-limits) für die Aufbewahrungsfenster, die der Hold übersteuert. # Audit-Logs Source: https://tale.dev/docs/de/platform/admin/governance/audit-logs Das Audit-Log ist die unveränderliche Aufzeichnung jeder folgenreichen Aktion in deiner Organisation. Jede Anmeldung, Rollenänderung, Anbieter-Bearbeitung, Agent-Speicherung, Workflow-Ausführung und jeder Sandbox-Aufruf landet hier mit Akteur, Ressource, Vorher-/Nachher-Status und Zeitstempel. Admins und Inhaber lesen das, wenn ein Audit fragt, wer eine Ressource wann angefasst hat, wenn ein Compliance-Officer einen Export braucht, oder wenn etwas schiefläuft und die Frage ist _wer hat um 03:14 was geändert_. Diese Seite ist die Referenz für die Spalten, die Filter, die Kategorien und die Exportformate. Das Aufbewahrungsfenster für Audit-Zeilen wird im selben Governance-Bereich unter der Aufbewahrungsrichtlinie gesetzt — halte es lang genug, damit deine Compliance-Anforderungen erfüllt sind, bevor Zeilen ausgesteuert werden. ## Ein durchgespielter Filter Um den Moment zu finden, in dem die Rolle eines Mitglieds geändert wurde, öffne **Einstellungen > Richtlinien > Audit-Logs**, setze den Filter **Kategorie** auf **Mitglied** und suche nach Akteur oder Ziel über den Namen. Jede Zeile öffnet die volle Payload — vorheriger Status, neuer Status, die IP, wenn die Anfrage über das Netz kam, der Akteurstyp (Benutzer, System, API, Workflow). Exportiere die gefilterte Auswahl über die Symbolleiste über der Tabelle als CSV oder JSON. ## Die Spalten | Name | Typ | Pflicht | Beschreibung | | ---------------- | -------- | ------- | ------------------------------------------------------------------------------------------- | | Zeitstempel | ISO 8601 | ja | Serverzeit, zu der die Aktion committet wurde. | | Aktion | string | ja | Die semantische Aktion — `update_member_role`, `provider_created`, `agent_saved`. | | Benutzer | string | ja | Anzeigename des Akteurs; `System`, `API` oder `Workflow`, wenn der Akteur keine Person ist. | | Ressource | string | ja | Die berührte Ressource — `agent`, `provider`, `member`, `workflow`. | | Kategorie | enum | ja | Auth, Mitglied, Daten, Integration, Workflow, Sicherheit, Admin, AI, Skill, Agent. | | Status | enum | ja | Erfolg, Fehlschlag, Verweigert. | | Geänderte Felder | JSON | nein | Der Diff zwischen vorherigem und neuem Status bei Update-Aktionen. | ## Filter Filtere nach Zeitraum, Kategorie, Status, Akteur, Ressource oder Freitext über die Aktionsnamen. Kombiniere Filter — ein Zeitraum plus die Kategorie **Sicherheit** plus Status **Verweigert** bringt die fehlgeschlagenen Anmeldeversuche in einem Fenster zum Vorschein. Der Filterzustand spiegelt sich in der URL, sodass ein gespeicherter Link dieselbe Ansicht wieder öffnet. ## Exportieren Zwei Exportformate werden ausgeliefert: CSV für Tabellenkalkulationen und JSON für nachgelagerte Systeme. Beide respektieren die aktiven Filter — was du exportierst, ist was du siehst. Setz die Filter, die du willst (der durchgespielte Filter oben ist das Muster), und wähl dann CSV oder JSON aus der Symbolleiste über der Tabelle. Große Exporte streamen als Download; die Symbolleiste meldet Fortschritt und meldet Abschluss mit Dateigröße und Zeilenanzahl. Die CSV kommt als `audit-logs-<timestamp>.csv`, eine Zeile pro Aktion, mit einer flachen Spalte pro Feld; Zeitstempel sind ISO 8601 in UTC und jeder Wert mit einem Komma wird in Anführungszeichen gesetzt: ```csv timestamp,action,category,actorEmail,actorId,actorType,actorRole,resourceType,resourceId,resourceName,status,errorMessage 2026-01-14T03:14:07.000Z,member.role_changed,Member,admin@acme.example,usr_8f3a,user,owner,member,usr_2b91,jordan@acme.example,success, 2026-01-14T03:15:22.000Z,provider.updated,Provider,admin@acme.example,usr_8f3a,user,owner,provider,prov_openai,OpenAI,success, ``` Der JSON-Export (`audit-logs-<timestamp>.json`) trägt dieselben Zeilen als vollständige Objekte plus die Felder, die CSV wegflacht — den `previousState`/`newState`-Diff und den `integrityHash` pro Zeile. Greif zu JSON, wenn ein nachgelagertes System die Vorher/Nachher-Payload braucht oder jede Zeile gegen die SHA-256-Kette neu verifizieren muss (siehe Abschnitt „Aufbewahrung und Integrität" weiter unten); greif zu CSV, wenn eine Person sie in einer Tabellenkalkulation öffnet. ## Aufbewahrung und Integrität Audit-Zeilen sind unveränderlich: Bearbeitungen und Löschungen werden selbst auditiert, und das Zeilenschema trägt einen Integritäts-Hash, den du gegen den Export prüfen kannst. Eine täglich geplante Prüfung verifiziert die Hash-Kette serverseitig erneut und schreibt einen `security`-Audit-Eintrag, wenn die Verifikation fehlschlägt — sodass Manipulation oder eine Löschung außer der Reihe auch dann auffällt, wenn niemand die manuelle Prüfung ausführt. Eine fehlgeschlagene Prüfung löst zusätzlich eine kritische In-App-Benachrichtigung an die Admins der Organisation aus und geht an Slack, wenn ein Slack-Benachrichtigungskanal konfiguriert ist. Die Aufbewahrung steht standardmäßig auf 90 Tagen und ist auf der Seite zur Aufbewahrungsrichtlinie konfigurierbar (30 bis 365 Tage). Zeilen, die altern, werden vom nächsten Cleanup-Lauf entfernt — es gibt kein Soft-Delete-Fenster für Audit-Daten. ## Wo das hingehört Das Audit-Log ist die Leseseite jedes anderen Governance-Features: Legal Hold benennt die platzierten Holds, Anfragen betroffener Personen protokollieren jeden Cascade-Schritt, die Run-code-Richtlinie protokolliert die URLs, die jede Sandbox zu erreichen versuchte. Wenn eine Frage mit _wer, wann, was_ beginnt, ist das Audit-Log die Antwort. Die Begleitseite ist die [Aufbewahrungsrichtlinie](/de/platform/admin/governance/policies-and-limits) — sie steuert, wie lange diese Zeilen bleiben, bevor Cleanup sie entfernt. # Papierkorb Source: https://tale.dev/docs/de/platform/admin/governance/trash Papierkorb ist die Wiederherstellungsoberfläche für die Zeilen, die die Aufbewahrung soft-gelöscht, aber noch nicht hart-gelöscht hat. Wenn ein Chat-Thread, ein Dokument, eine Prompt-Vorlage oder ein Workflow-Lauf sein Aufbewahrungsfenster überschreitet, wandert er für das konfigurierte Kulanzfenster hierhin, bevor der nächste Cleanup-Lauf ihn endgültig entfernt. Admins und Inhaber lesen diese Seite, wenn ein Mitglied ein gelöschtes Artefakt zurückbittet, wenn ein Workflow das Falsche gelöscht hat, oder wenn ein Audit wissen muss, ob eine Zeile noch wiederherstellbar ist. ## Eine durchgespielte Wiederherstellung Um einen Chat-Verlauf-Thread wiederherzustellen, öffne **Einstellungen > Richtlinien > Papierkorb** und stelle den Filter **Kategorie** auf **Chatverlauf**. Jede Zeile trägt den Typ, den Namen, den Eigentümer, den Status und wann sie verworfen wurde. Klick auf **Wiederherstellen** in der Zeile, bestätige im Dialog, und die Zeile kehrt in ihre Quellliste zurück — Chat-Threads erscheinen wieder im Konversations-Posteingang, Dokumente in der Wissensdatenbank, Prompts in der Prompt-Bibliothek. Eine durch Aufbewahrung abgelaufene Zeile wiederherzustellen verlangt das Tippen von `restore` zur Bestätigung und wird als Überschreibung der Aufbewahrungsrichtlinie auditiert. ## Die zwei Status **Verworfen** ist der normale Soft-Delete-Zustand. Das Aufbewahrungsfenster der Zeile ist abgelaufen, sie ist in den Papierkorb gewandert, und das Kulanzfenster tickt noch. Wiederherstellen führt die Zeile in ihre Quellliste zurück, ohne die Richtlinie zu überschreiben. **Abgelaufen** ist der zweite Zustand — das Kulanzfenster ist abgelaufen und die Zeile ist für die endgültige Löschung im nächsten Cleanup vorgemerkt. Wiederherstellen ist weiterhin möglich, aber es ist eine Überschreibung: der Dialog verlangt, dass du `restore` tippst, und das Audit-Log dokumentiert die Überschreibung mit deinem Namen. ## Die Kategorien Der Papierkorb hält Zeilen aus vielen Kategorien. Der Kategoriefilter wechselt die Ansicht pro Tab: - Chatverlauf (Threads) - Dokumente - Temporäre Dateien - Prompt-Vorlagen - Nachrichten-Feedback - Kunden - Lieferanten - Externe Konversationen - Nachrichten-Metadaten - Workflow-Läufe - Workflow-Trigger-Logs - Nutzungsbuch - Audit-Logs - Chat-Filter-Ereignisse - Memory-Audit Jede Kategorie respektiert ihr eigenes Aufbewahrungsfenster und ihr eigenes Kulanzfenster — gesetzt in der Aufbewahrungsrichtlinie unter [Richtlinien und Limits](/de/platform/admin/governance/policies-and-limits). ## Interaktion mit Legal Hold Zeilen unter Legal Hold erscheinen nicht im Papierkorb — der Hold heftet sie außer Reichweite jedes Aufbewahrungs-Schritts. Wenn du versuchst, eine gehaltene Zeile aus ihrer Quellliste zu löschen, lehnt Tale mit der Nachricht **Löschen ist durch einen aktiven Legal Hold gesperrt** ab. Den Hold aufheben lässt die Aufbewahrung die Zeile durch das Papierkorb-Fenster laufen, wie andere Kategorien fließen. ## Das Kulanzfenster Das Kulanzfenster ist pro Kategorie in der Aufbewahrungsrichtlinie konfigurierbar. Ein Kulanz-Wert von null überspringt den Papierkorb komplett — der Cleanup-Lauf löscht die Zeile hart, sobald die Aufbewahrung auslöst. Ein Wert über null hält die Zeile diese Anzahl Tage im Papierkorb und zeigt sie hier für das Admin-Fenster, in dem Wiederherstellen noch billig ist. ## Wo das hingehört Papierkorb ist die zweite Chance, die die Aufbewahrung jeder Kategorie gibt, bevor der Cleanup-Lauf eine Zeile endgültig entfernt. Er paart mit [Richtlinien und Limits](/de/platform/admin/governance/policies-and-limits) — die Aufbewahrungsseite setzt die Fenster; diese Seite ist die Wiederherstellungsansicht, in die diese Fenster speisen. Die Begleitseite ist [Legal Hold](/de/platform/admin/governance/legal-hold) — der einzige Mechanismus, der die Aufbewahrung schlägt, bevor eine Zeile überhaupt im Papierkorb landet. # Anfragen betroffener Personen Source: https://tale.dev/docs/de/platform/admin/governance/data-subject-requests Anfragen betroffener Personen ist der Workflow, den Tale für die Einhaltung von DSGVO Artikel 17 (Recht auf Löschung) und das entsprechende CCPA-Recht nach kalifornischem Recht ausliefert. Jede Anfrage wird zu einem Beleg: er nennt die betroffene Person, den Begründungs-Code, die SLA-Frist und die Kaskade von Zeilen, die das System über Threads, Dokumente, Workflow-Ausführungen und persönliche Prompt-Vorlagen hinweg gelöscht hat. Admins und Inhaber lesen diese Seite, wenn eine Person eine Anfrage stellt, wenn eine Frist näher rückt, oder wenn ein Audit den Beleg einer vergangenen Löschung verlangt. <Frame caption="Governance > Anfragen betroffener Personen — die DSAR-Governance-Richtlinie (Cooling-off-Fenster, Vier-Augen-Freigabe, Tageslimit) über der Liste der Anfrage-Belege mit Anfrage einreichen."> ![Die Governance-Seite Anfragen betroffener Personen zeigt das Cooling-off-Fenster, 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.](/images/platform/governance-data-subject-requests.webp) </Frame> ## Eine durchgespielte Einreichung Um eine Anfrage einzureichen, öffne **Einstellungen > Richtlinien > Anfragen betroffener Personen** und klick auf **Anfrage einreichen**. Wähle die betroffene Person, wähle einen Begründungs-Code (Einwilligung widerrufen, nicht mehr erforderlich, unrechtmäßige Verarbeitung, rechtliche Verpflichtung, Widerspruch, minderjährige Person oder Vertragsende) und füge eine Freitext-Begründung hinzu. Die Anfrage tritt in ein Cooling-off-Fenster ein, bevor die Kaskade läuft — jeder Admin kann während des Fensters abbrechen. Nach Ablauf des Fensters löscht die Kaskade die Threads, Dokumente, Workflow-Ausführungen, RAG-Embeddings und persönlichen Prompts der Person, und der Beleg dokumentiert die Zähler für jede Kategorie. ## Status-Lebenszyklus | Name | Default | Beschreibung | | ------------------- | -------------- | -------------------------------------------------------------------------------------------------- | | Ausstehend | Anfangszustand | Die Anfrage ist eingereicht und wartet auf das Cooling-off-Fenster oder die zweite Admin-Freigabe. | | Wartet auf Freigabe | Vier-Augen | Ein zweiter Admin muss freigeben, bevor die Kaskade läuft. | | Läuft | mid-cascade | Die Kaskade läuft; Teilzähler aktualisieren sich, sobald jede Kategorie fertig ist. | | Abgeschlossen | terminal | Jede Kategorie ist ohne Fehler gelöscht. | | Teilweise | terminal | Einige Zeilen wurden übersprungen — meist hat ein Legal Hold sie blockiert. | | Fehlgeschlagen | terminal | Die Kaskade traf auf einen Fehler; der Beleg benennt die fehlgeschlagene Kategorie. | | Blockiert | terminal | Ein aktiver Legal Hold blockiert jeden Kaskade-Schritt. | | Abgebrochen | terminal | Ein Admin hat vor Ablauf des Cooling-off-Fensters abgebrochen. | ## SLA-Verfolgung Jede Anfrage trägt eine Service-Level-Frist — standardmäßig 30 Tage ab Einreichung. Die Anfragenliste zeigt verbleibende Tage oder ein Überfällig-Badge pro Zeile. Artikel 12(3) DSGVO erlaubt eine einmalige Verlängerung für komplexe Fälle; die Aktion **Frist verlängern** vermerkt die Verlängerung auf dem Beleg mit dem Namen des anfordernden Admins und einer Begründung. ## Interaktion mit Legal Hold Daten einer betroffenen Person werden _nicht_ gelöscht, solange sie auf Legal Hold liegen. Zeilen unter Hold erscheinen im Beleg in den Per-Kategorie-Zählern als **Durch Legal Hold übersprungen**; den Hold aufheben und die Anfrage erneut versuchen schließt die Löschung ab. Der Status Blockiert greift, wenn ein Hold von Anfang an jede Kategorie abdeckt — die Kaskade läuft nicht, und der Beleg spiegelt die Blockade. ## Die Kaskade-Kategorien Der Beleg schlüsselt die gelöschten Zeilen nach Kategorie auf — Threads, Dokumente, Workflow-Ausführungen, Prompt-Vorlagen, aus dem Vektorspeicher entfernte RAG-Dokumente. Lies das Drawer für Zähler und die Audit-Zeitleiste; das Audit-Log im selben Governance-Bereich trägt die volle Ereigniskette (`gdpr_erasure_requested`, `gdpr_erasure_executed`, `gdpr_erasure_extended`, `gdpr_erasure_cancelled`). ## Wo das hingehört Anfragen betroffener Personen ist das Compliance-Gesicht der Aufbewahrung — der auditierte, vier-Augen-kontrollierte Pfad, der eine bestimmte Person auf Anfrage löscht, statt der zeitgesteuerten Sweeps, die die Aufbewahrung über alle hinweg läuft. Die Begleitseite ist [Legal Hold](/de/platform/admin/governance/legal-hold) — sie deckt ab, wie Aufbewahrung und Löschungs-Kaskaden für Rechtsstreitigkeiten pausiert werden, bevor sie laufen. # Feedback-Analyse Source: https://tale.dev/docs/de/platform/admin/governance/feedback-analytics Feedback-Analyse ist das Dashboard, das die Per-Nachricht-Daumen und die Per-Chat-Bewertungen in Trendlinien verwandelt. Mitglieder hinterlassen das Feedback inline im Chat; diese Seite aggregiert es pro Agent, pro Modell und über die Zeit, sodass die Regression aus der Stimmänderung letzter Woche als Zahl sichtbar ist und nicht als Bauchgefühl. Admins und Inhaber lesen diese Seite, wenn ein Modellwechsel wie eine Verschlechterung aussieht, wenn ein Agent schlechter abschneidet als die anderen, oder wenn die Führung die grobe Qualitätshaltung jedes Agents in der Organisation will. ## Eine durchgespielte Detailansicht Öffne **Einstellungen > Richtlinien > Feedback** und die Default-Ansicht ist das organisationsweite Verhältnis über die letzten 30 Tage. Wechsle die Aufschlüsselung auf **Nach Agent**, um das Verhältnis pro Agent zu sehen — sortiere nach Feedback-Volumen, um die Agents zu finden, die Mitglieder tatsächlich nutzen, klick dann in einen hinein, um seine Modellhistorie neben demselben Verhältnis über die Zeit zu sehen. Die Ansicht Aufteilung nach Modell sind dieselben Daten, geschnitten auf das Modell, das jede bewertete Antwort erzeugt hat. ## Die zwei Signale **Daumen-Feedback** ist das Per-Nachricht-Signal — ein Daumen hoch oder ein Daumen runter auf eine Agent-Antwort. Der Daumen trägt einen optionalen Freitext-Kommentar; der Kommentar ist pro Zeile und fließt nie ins Verhältnis. Mitglieder können beides hinterlassen, eines bearbeiten oder ganz zurückziehen; die Zeitleiste zeigt den jeweils letzten Stand. **Chat-Bewertungen** ist das Per-Konversations-Signal — die Bewertung von eins bis fünf Sternen, die am Ende einer Konversation auftaucht. Bewertungen tragen auch einen optionalen Kommentar. Chat-Bewertungen sind gröber als Daumen und nützlich, um die Agent-Stimmung über viele Runden zu verfolgen, wo einzelne Daumen Rauschen wären. ## Aufschlüsselungen Das Dashboard schneidet nach drei Dimensionen: - **Agent** — jeder Agent in der Organisation bekommt seine eigene Zeile mit Verhältnis, Volumen und Trend. - **Modell** — jedes Modell, das eine bewertete Antwort erzeugt hat, trägt bei; nützlich beim Vergleich eines Primärmodells mit seinem Fallback. - **Zeit** — der Trend ist täglich für die letzten 30 Tage und wöchentlich für längere Fenster. ## Freitext-Kommentare Kommentare erscheinen unter den aggregierten Zahlen als Liste. Sortiere nach Aktualität oder nach Sentiment; klick durch zur Konversation im Kontext, um zu sehen, worauf die bewertete Antwort reagiert hat. Kommentare unterliegen derselben Aufbewahrungsrichtlinie wie die Konversationen, zu denen sie gehören; wird ein Thread gelöscht oder verworfen, gehen die Kommentare mit. ## Wo das hingehört Feedback-Analyse ist der Puls jedes Agents in der Organisation — der Ort, an dem eine Regression in Stimme oder Modellverhalten auftaucht, bevor jemand sie meldet. Die Begleitseite ist [Nutzungs-Analyse](/de/platform/admin/governance/usage-analytics) — dieselben Agents und Modelle, geschnitten nach Kosten und Token-Volumen statt nach Qualität. # Agents (Admin-Sicht) Source: https://tale.dev/docs/de/platform/admin/agents Die Admin-Sicht auf Agents ist das organisationsweite Verzeichnis jedes Agents, der in Tale existiert, egal wer ihn gebaut hat. Redakteure und Entwickler sehen nur die Agents, auf die sie in ihrem eigenen Bereich Zugriff haben; Admins und Inhaber sehen alle, plus die per-Agent-Steuerungshebel und den per-Agent-Audit-Pfad. Diese Seite behandelt die Admin-Oberfläche — was die Tabelle zeigt, was ein Admin ändern kann und was unter der Kontrolle des Agent-Eigentümers bleibt. Diese Seite lehrt dich nicht, einen Agent zu bauen. Das ist die Redakteurs-Sicht unter [Agents](/de/platform/agents/concepts). Was folgt, ist die Aufsichtsseite: wie du einen Agent findest, wie du eingreifst, wenn einer Aufmerksamkeit braucht, und wie die Rollengrenzen dabei halten. <Frame caption="Die organisationsweite Agents-Liste — ein Ordner zu seinen Agent-Zeilen aufgeklappt, jede mit Modell und Kategorie. Ein Admin sieht hier jeden Agent der Organisation."> ![Die Agents-Liste mit einem aufgeklappten Ordner, der Agent-Zeilen zeigt, jede nennt einen Agent samt primärem Modell und Kategorie.](/images/platform/agents-list-expanded.webp) </Frame> ## Was die Tabelle zeigt Öffne **Einstellungen > Agenten**, um auf der organisationsweiten Liste zu landen. Jede Zeile nennt einen Agent und zeigt sein primäres Modell, seine Kategorie, das Team, dem er gehört (falls vorhanden), und das Datum der letzten Bearbeitung. Die Liste ist nach Namen suchbar und nach Kategorie, Team und Status (aktiv oder deaktiviert) filterbar. Die Standardsortierung ist „zuletzt bearbeitet zuerst" — nützlich, wenn du sehen willst, was sich seit dem letzten Blick geändert hat. Ein Klick auf eine Zeile öffnet denselben Agent-Editor, den ein Redakteur oder Entwickler sehen würde, aber mit der Admin-Linse: jeder Tab ist sichtbar, jede Bindung ist editierbar, und der Audit-Log-Tab zeigt den vollen Bearbeitungsverlauf mit dem Akteur und dem Diff pro Speicherung. ## Was ein Admin tun kann, was ein Redakteur nicht kann Admins erben jede Berechtigung, die Redakteur und Entwickler auf der Agent-Oberfläche tragen. Darüber hinaus fügt die Admin-Sicht drei Steuerungs-Bewegungen hinzu: - **Agent deaktivieren.** Ein deaktivierter Agent erscheint nicht mehr in Pickern und antwortet nicht mehr auf neue Anfragen, aber seine Konversationen, Ausführungen und der Audit-Pfad bleiben erhalten. Reaktivieren stellt das vorherige Verhalten wieder her. Greif zu Deaktivieren, wenn ein Agent sich falsch verhält und du ihn stoppen musst, ohne den Kontext zu verlieren. - **Eigentum übertragen.** Der Eigentümer eines Agents ist das Team oder Mitglied, das für ihn verantwortlich ist. Übertragen verschiebt den Agent zu einem anderen Team oder Mitglied; der vorherige Eigentümer verliert Schreibzugriff, außer er teilt das neue Team. Greif zu Übertragen, wenn ein Team reorganisiert wird oder ein Eigentümer geht. - **Eine Governance-Richtlinie anwenden.** Admins können einem Agent eine Governance-Richtlinie anhängen — erforderliche Genehmigungen bei Schreibvorgängen, erlaubte Tool-Familien, erlaubte Integrationen. Die Richtlinie überschreibt die eigene Konfiguration des Agents bei Konflikten; der Eigentümer sieht die Richtlinie als schreibgeschütztes Badge im Editor. ## Was beim Agent-Eigentümer bleibt Die meiste tägliche Bearbeitung bleibt bei der Person, die den Agent gebaut hat. Umbenennen, Anweisungen bearbeiten, die Wissensbindungen anpassen, Tools umschalten, Modelle wechseln, neue Versionen veröffentlichen — all das passiert im Agent-Editor unter den Berechtigungen des Eigentümers. Die Admin-Sicht dient dem Eingreifen, nicht der Übernahme. Wenn du regelmäßig fremde Agents bearbeitest, ist die richtige Antwort meist eine Governance-Richtlinie, die das Verhalten eingrenzt, keine manuelle Änderung. ## Audit und Verlauf Jede Speicherung auf einem Agent landet im Audit-Log mit Akteur, Zeitstempel und dem Feld, das sich geändert hat. Die Admin-Sicht legt den per-Agent-Ausschnitt dieses Logs unter dem **Verlauf**-Tab im Agent-Editor frei. Dieselben Daten sind auch aus dem organisationsweiten Audit-Log unter **Einstellungen > Richtlinien** erreichbar. ## Wo das hingehört Die Admin-Sicht auf Agents ist das Aufsichts-Pendant zur Bau-Sicht des Redakteurs — gleiche Agents, andere Linse. Greif sie meistens nur, wenn etwas Aufmerksamkeit braucht; die tägliche Arbeit passiert im Agent-Editor unter [Agent-Konzepte](/de/platform/agents/concepts). Wenn die richtige Antwort darin liegt, Verhalten für eine ganze Klasse von Agents einzugrenzen statt für einen einzelnen, ist die nächste Lektüre die Governance-Richtlinien-Oberfläche — siehe [Mitglieder und Rollen](/de/platform/admin/members-and-roles) für die Anbindung der Richtlinien an Rollen. # Mitglieder und Rollen Source: https://tale.dev/docs/de/platform/admin/members-and-roles Mitglieder sind die Personen in deiner Organisation, die sich bei Tale anmelden können. Rollen kontrollieren, was jedes Mitglied tun darf — lesen, schreiben, konfigurieren, regeln. Diese Seite ist die kanonische Referenz für die sechs Rollen und die Berechtigungen pro Ressource, die jede Rolle trägt. Sechs Rollen decken nahezu jedes Team ab, an das Tale ausgeliefert wird. Admins und Inhaber lesen diese Seite, wenn sie ein Team zum ersten Mal aufsetzen, wenn ein Audit fragt, wer welchen Zugriff hat, oder wenn sie wissen müssen, ob sie einem neuen Kollegen Redakteur oder Entwickler geben. <Frame caption="Der Mitglieder-Abschnitt unter Einstellungen > Organisation — jeder Account und die Rolle, die ihn begrenzt."> ![Die Organisations-Einstellungsseite mit ihrem Mitglieder-Abschnitt, der den Inhaber des Workspace und eine Schaltfläche Mitglied hinzufügen zeigt.](/images/get-started/settings-organization-members.webp) </Frame> ## Ein Mitglied hinzufügen Um eine Person in deine Organisation aufzunehmen, öffne **Einstellungen > Organisation**, scroll zum Abschnitt **Mitglieder** und klick auf **Mitglied hinzufügen**. Trag **Name**, **E-Mail** und **Rolle** ein und vergib ein **Passwort** — Tale verschickt keine Einladungs-E-Mail, deshalb ist ein Passwort erforderlich, um ein neues Konto zu erstellen. (Gehört die E-Mail bereits zu einem Tale-Konto, wird kein Passwort verlangt: die Person meldet sich mit ihren bestehenden Zugangsdaten an und wird einfach dieser Organisation hinzugefügt.) Beim **Mitglied hinzufügen** zeigt Tale die neuen Zugangsdaten **einmalig** an, mit dem Hinweis, sie jetzt zu speichern — sie werden nicht erneut angezeigt. Gib sie dem neuen Mitglied auf einem anderen Weg weiter; es gibt keine Reset-E-Mail. Wer sein Passwort später vergisst, wendet sich an einen Admin, der im selben Mitglieder-Abschnitt ein neues setzen kann. Wähl die Rolle im Formular, bevor du absendest; sie später hochzustufen oder zu ändern ist eine Ein-Klick-Änderung im selben Mitglieder-Abschnitt. ## Die sechs Rollen **Inhaber** hat jede Berechtigung, die Admin hat, plus die eine, die Admin fehlt: Eigentum übertragen und die Organisation löschen. Die meisten Teams haben genau einen Inhaber; manche behalten zwei für Kontinuität. **Admin** regelt die Organisation: Mitglieder, Anbieter, Branding, Governance-Richtlinien, Integrationen, das Audit-Log. Admins tun alles, was Redakteur und Entwickler tun, plus die Konfigurationsoberfläche. Sie können das Eigentum nicht übertragen. **Entwickler** baut: Agents, Workflows, Integrationen, API-Keys, MCP-Server. Entwickler können jede Ressource lesen und in die meisten schreiben, inklusive Governance-Richtlinien (nur lesen). Greif zu Entwickler, wenn jemand die API-Ebene und das Integrations-Tooling braucht. **Redakteur** kuratiert und betreibt: Agents, die Wissensdatenbank (Dokumente, Kunden, Produkte, Lieferanten, Websites), den Konversations-Posteingang, Genehmigungen, die Prompt-Bibliothek. Redakteure können Workflows lesen, aber nicht ändern; sie können Integrationen lesen, aber nicht konfigurieren. Greif zu Redakteur, wenn jemand die tägliche Produktarbeit erledigt, ohne die API- oder Integrationsebene zu berühren. **Mitglied** nutzt: Chat, durchsucht die Wissensdatenbank, liest Konversationen und Genehmigungen, die ihm zugewiesen sind. Mitglieder schreiben nur an Nachrichten-Feedback (Daumen hoch / runter). Greif zu Mitglied als Default — die meisten Benutzer in den meisten Organisationen sind Mitglieder. **Deaktiviert** hat keine Berechtigungen. Nutz das, um Zugriff zu entziehen, ohne den Account zu löschen; Transkripte und Audit-Historie bleiben intakt, und ein Reaktivieren stellt die vorherige Rolle wieder her. ## Die Berechtigungs-Matrix | Ressource | Inhaber | Admin | Entwickler | Redakteur | Mitglied | Deaktiviert | | ------------------------- | ------- | ----- | ---------- | --------- | -------- | ----------- | | Agents | R / W | R / W | R / W | R / W | R | — | | Dokumente | R / W | R / W | R / W | R / W | R | — | | Produkte | R / W | R / W | R / W | R / W | R | — | | Kunden | R / W | R / W | R / W | R / W | R | — | | Lieferanten | R / W | R / W | R / W | R / W | R | — | | Projekte | R / W | R / W | R / W | R / W | R | — | | Websites | R / W | R / W | R / W | R / W | R | — | | Konversationen | R / W | R / W | R / W | R / W | R | — | | Konversations-Nachrichten | R / W | R / W | R / W | R / W | R | — | | Genehmigungen | R / W | R / W | R / W | R / W | R | — | | Workflow-Ausführungen | R / W | R / W | R / W | R | R | — | | Workflow-Processing | R / W | R / W | R / W | R | R | — | | Integrationen | R / W | R / W | R / W | R | R | — | | OneDrive-Sync-Konfigs | R / W | R / W | R / W | R | R | — | | Prompt-Templates | R / W | R / W | R / W | R / W | R | — | | Audit-Logs | R / W | R / W | R / W | R / W | R | — | | Governance-Richtlinien | R / W | R / W | R | R | R | — | | Nachrichten-Feedback | R / W | R / W | R / W | R / W | R / W | — | | MCP-Server | R / W | R / W | R / W | R | R | — | R = lesen, W = schreiben, — = kein Zugriff. Die Matrix ist die autoritative Beschreibung, was jede Rolle über die Ressourcen tun kann, die Tale verfolgt; die Zeilen sind dieselbe Menge, die das In-Produkt-Berechtigungssystem zur Request-Zeit nutzt. ## Die Einstellungs-Oberfläche und das Menü Mitglieder, Redakteure und deaktivierte Benutzer sehen die Konfigurationsoberfläche nicht — nur ihre eigenen persönlichen Einstellungen. Entwickler sehen die Organisationseinstellungen, aber nicht den Governance-Unterzweig (außer Lese-Ansichten). Admins und Inhaber sehen alles. Das Einstellungsmenü ist gruppiert in **Persönlich** (Konto, Einstellungen, Umgebung — jede Rolle), **Organisation** (der Mitglieder-Abschnitt, Teams, KI-Anbieter, Branding, Governance und der Rest — Admin und Inhaber, wobei Entwickler eine Teilmenge sehen) und **Entwicklung** (die API- und Data-Residency-Oberfläche). Governance ist ein Eintrag innerhalb der Organisations-Gruppe, keine eigene Gruppe, und braucht Admin-Zugriff. ## Randfälle **Eigentum übertragen** verlangt, dass ein bestehender Inhaber einen aktuellen Admin oder Inhaber nominiert; die neue Inhaber-Rolle wirkt sofort. Der vorherige Inhaber wird zu Admin, außer er wird explizit herabgestuft. **Warnung „letzter Admin".** Der Mitglieder-Abschnitt warnt, wenn der letzte Admin oder Inhaber entfernt oder herabgestuft wird. Die Aktion ist erlaubt — Tale sperrt dich nicht aus — aber du solltest mindestens zwei Admin- oder Inhaber-Accounts für Kontinuität halten. **Zwei-Faktor zurücksetzen** liegt auf der Zeile des Mitglieds im Mitglieder-Abschnitt. Zurücksetzen entfernt den zweiten Faktor; der nächste Sign-in registriert neu. ## Wo das hingehört Rollen sind die Zugriffsoberfläche, die jede andere Admin-Seite berührt: SSO authentifiziert sie, API-Keys gehören ihnen, Audit-Logs benennen sie, Governance-Richtlinien grenzen Verhalten nach Rolle ein. Die nächste Lektüre hängt davon ab, was du als Nächstes tust. Wenn du Sign-in an deinen Identitätsanbieter verdrahtest, behandelt [Authentifizierung](/de/self-hosted/configuration/authentication) die vier Sign-in-Modi. Wenn du Zugriff nach Team statt nur nach Rolle eingrenzt, deckt [Teams](/de/platform/admin/teams) die Team-Ebene dieser Eingrenzung ab. # Teams Source: https://tale.dev/docs/de/platform/admin/teams Ein Team ist eine benannte Gruppe von Mitgliedern, die sich Zugriff auf Agents, Prompts, Projekte, Integrationen und Konversationen teilt. Wo Rollen definieren, was eine Person tun _kann_, definieren Teams, in welchem Ausschnitt der Organisationsdaten diese Person arbeitet. Die meisten Organisationen landen bei einer Handvoll Teams — Support, Vertrieb, Betrieb — und die meisten alltäglichen Berechtigungs-Entscheidungen liegen auf der Team-Grenze, nicht auf der Rollen-Grenze. Admins verwalten Teams unter **Einstellungen > Teams**. Diese Seite ist die Referenz dafür, was ein Team besitzt, wie Mitgliedschaft funktioniert und wie die Team-Grenze mit den rollenbasierten Berechtigungen aus [Mitglieder und Rollen](/de/platform/admin/members-and-roles) zusammenspielt. Lies sie einmal, wenn du die Teams der Organisation aufsetzt; komm wieder, wenn du umorganisierst. <Frame caption="Einstellungen > Teams — jedes Team der Organisation mit seiner Mitgliederzahl, neben der Aktion Team erstellen."> ![Die Teams-Einstellungsseite listet drei Teams — Growth, Platform engineering und Customer success —, jedes mit einem Mitglied und dem Zeitpunkt, an dem es hinzugefügt wurde, neben der Schaltfläche Team erstellen.](/images/platform/settings-teams.webp) </Frame> ## Was ein Team besitzt Ein Team hält Mitgliedschaft und eine Menge ihm zugeordneter Ressourcen. Die Ressourcen sind: - **Agents** — Agents, die mit Team-Scope erstellt wurden, sind nur für Mitglieder dieses Teams sichtbar und editierbar. Organisationsweite Agents bleiben für alle mit passender Rolle sichtbar. - **Prompts** — gespeicherte Prompts mit Sichtbarkeit `Team` erscheinen nur für die Mitglieder dieses Teams. Persönliche Prompts bleiben privat beim Eigentümer; Globale Prompts sind organisationsweit sichtbar. - **Projekte** — Projekte können einem Team zugewiesen werden; die Mitglieder des Teams erben den Projekt-Zugriff, ohne einzeln hinzugefügt zu werden. - **Integrationen** — Integrationen, die auf bestimmte Teams beschränkt sind (über den Hebel **Erlaubte Teams** unter **Einstellungen > Integrationen**), erscheinen nur in Pickern dieser Teams. - **Konversationen** — Kundenkanal-Konversationen können an ein Team geroutet werden; der Inbox-Filter respektiert den Team-Scope. Eine Ressource ohne Team-Scope bleibt für alle sichtbar, deren Rolle es erlaubt. Teams sind eine _zusätzliche_ Eingrenzungsebene — sie engen Sichtbarkeit ein, weiten sie nie aus. ## Ein Team erstellen Öffne **Einstellungen > Teams** und klick auf **Team erstellen**. Gib dem Team einen Namen (`Support`, `Vertrieb`, `Betrieb`) und eine optionale Beschreibung; der Name erscheint überall, wo das Team auftaucht — Picker, Badges, die Tabs der Prompt-Bibliothek, das Erlaubte-Teams-Feld der Integration. Speichern erstellt ein leeres Team, das du aus der Team-Zeile mit Mitgliedern füllen kannst. Die Team-Zeile trägt drei Untersichten: **Mitglieder** (wer im Team ist), **Ressourcen** (was das Team besitzt) und **Einstellungen** (Name, Beschreibung und Lebenszyklus des Teams). Die Ressourcen-Sicht ist der einfachste Weg, zu sehen, wohin ein Team reicht; sie dient zusätzlich als Audit-Oberfläche, wenn jemand fragt, warum ein Team einen bestimmten Agent sieht. ## Mitglieder hinzufügen und entfernen Öffne die Team-Zeile und klick auf **Mitglieder hinzufügen**. Der Picker listet die Mitglieder der Organisation; eines anzuhaken fügt es dem Team hinzu. Ein Mitglied kann mehreren Teams angehören; sein Zugriff ist die Vereinigung jedes Teams, in dem es ist, plus der organisationsweiten Reichweite seiner Rolle. Ein Mitglied aus einem Team zu entfernen, entzieht beim nächsten Request die team-gebundene Sichtbarkeit; laufende Chats werden fertig, aber der nächste Thread sieht die Ressourcen des Teams nicht mehr. ## Team versus Rolle Die Rolle entscheidet, was eine Person tun darf; das Team entscheidet, woran. Ein Mitglied-Rollen-Benutzer im Support-Team kann die Agents des Support-Teams lesen, aber nicht bearbeiten; ein Entwickler-Rollen-Benutzer im Support-Team kann die Agents des Support-Teams lesen und schreiben, aber die des Vertriebs nicht sehen. Teams gewähren nie Fähigkeiten, die der Rolle fehlen; Rollen weiten Sichtbarkeit nie über den Team-Scope hinaus. Wenn du eine Berechtigungs-Entscheidung brauchst, die bestehende Rollen und Teams nicht ausdrücken können, ist der nächste Hebel eine Governance-Richtlinie — siehe [Mitglieder und Rollen](/de/platform/admin/members-and-roles) dafür, wie Richtlinien sich an Rollen heften, und den Governance-Bereich für die Richtlinien-Felder selbst. ## Ein Team löschen Klick auf die Team-Zeile, dann auf **Team löschen**. Löschen ist Hard-Stop — das Team ist weg, jede team-gebundene Ressource, die es besaß, wechselt auf organisationsweite Sichtbarkeit, und Mitglieder verlieren den team-gebundenen Ausschnitt ihres Zugriffs. Es gibt kein Undo; verwaiste Ressourcen bleiben für alle erreichbar, deren Rolle es erlaubt, was selten das richtige Ergebnis ist. Greif zu Löschen, wenn ein Team wirklich aufgelöst wird, nicht wenn es umorganisiert wird. ## Wo das hingehört Teams sind die Eingrenzungsebene direkt unter Rollen — Rollen sagen _was_, Teams sagen _wo_. Die natürliche nächste Lektüre hängt von der Ressource ab, die du eingrenzt: [Prompt-Bibliothek](/de/platform/workspace/prompt-library) dafür, wie Prompts sich an Teams binden, [Integrationen (Admin-Sicht)](/de/platform/admin/integrations) für den Hebel Erlaubte Teams, und [Projekte](/de/platform/projects/overview) für die Projekt-zu-Team-Zuweisung. # Integrationen (Admin-Sicht) Source: https://tale.dev/docs/de/platform/admin/integrations Einstellungen > Integrationen ist die Anmeldedaten-Oberfläche für jedes Drittanbieter-System, mit dem Tale im Namen der Organisation spricht. Admins installieren Integrationen einmal; Agents, Workflows und die Dokumenten-Pipeline nutzen sie überall sonst. Diese Seite behandelt die Admin-Seite — was die Liste zeigt, wie Installation und Rotation funktionieren, was ein Admin eingrenzen kann und wie sich die Oberfläche von MCP-Servern unterscheidet. Die funktionale Geschichte jeder Integration (was sie tut, welche Scopes sie verlangt, was ein Agent aufrufen kann) liegt einen Tab weiter auf den Per-Integrations-Seiten und in der übergreifenden Konzeptseite. Was folgt, ist die Betriebsoberfläche: installieren, rotieren, einschränken, widerrufen. <Frame caption="Der Integrations-Katalog unter Integration hinzufügen — jeder Connector, den Tale mitbringt, nach Kategorie filterbar."> ![Der Integrations-Katalog mit einem Raster aus Connector-Karten — Slack, Gmail, Google Drive, GitHub, Tavily und mehr — jede mit einer Verbinden-Aktion.](/images/platform/integrations-catalog.webp) </Frame> ## Was die Liste zeigt Öffne **Einstellungen > Integrationen**, um auf den installierten Integrationen der Organisation zu landen. Jede Zeile nennt eine Integration, zeigt ihre Kategorie (Kommunikation, Speicher, Identität, Wissen, Quellcode, Handel, KI), den Anmeldedaten-Typ (OAuth2, API-Schlüssel, App-Token) und den Verbindungs-Status (verbunden, ausstehend, Fehler). Die Liste ist nach Kategorie und Status filterbar. Der Katalog verfügbarer Integrationen sitzt einen Klick entfernt unter **Integration hinzufügen**. Der Katalog liefert aktuell Slack, Microsoft Teams, Discord, Gmail, Outlook, Twilio, Microsoft 365, Google Drive, Confluence, WebDAV, Tavily, GitHub, Shopify und AI-Image; derselbe Katalog ist die Quelle, die die Integrations-Übersicht dokumentiert. ## Eine Integration installieren Wähl eine Integration aus dem Katalog und klick auf **Verbinden**. Die Integration deklariert den erwarteten Anmeldedaten-Typ und die benötigten Scopes; Tale geht für OAuth-Integrationen den OAuth-Tanz und zeigt ein Formular für API-Schlüssel-Integrationen. Sobald die Anmeldedaten ankommen, prüft Tale sie mit einem No-op-Aufruf gegen das Upstream-System, bevor gespeichert wird — ein Fehler erscheint als Verbindungsfehler mit der Upstream-Meldung dran. Einige Integrationen tragen Unteroptionen bei der Installation. Microsoft 365 lässt dich wählen, ob OneDrive-Sync, SharePoint-Sync, beide oder nur Single Sign-on aktiviert werden; GitHub lässt dich die Repositories wählen, auf die die Organisation Zugriff erhält; Slack fragt, in welchen Kanälen der Bot posten darf. Die Unteroptionen lassen sich später aus der Zeile der Integration ändern, ohne neu zu installieren. ## Definitionen aus dem mitgelieferten Katalog aktualisieren Die Definition jeder Integration — ihr Konfigurationsschema, ihr Connector, ihr Icon — wird beim Anlegen der Organisation kopiert und bleibt danach unangetastet; ein Plattform-Upgrade ändert sie also nie hinter deinem Rücken. **Mitgelieferte Integrationen aktualisieren** im Menü **Integration hinzufügen** ersetzt jede mitgelieferte Definition, die vom aktuellen Katalog abweicht, durch die neueste Version. Anmeldedaten, Secrets und selbst hinzugefügte Integrationen bleiben unberührt; die vorherige Version jeder ersetzten Definition bleibt auf dem Server erhalten, sodass ein Operator sie wiederherstellen kann. ## Anmeldedaten rotieren Zum Rotieren öffne die Zeile der Integration und klick auf **Anmeldedaten rotieren**. OAuth-Integrationen gehen den Tanz nochmal mit denselben Scopes; API-Schlüssel-Integrationen zeigen ein Feld für den neuen Schlüssel. Die alte Anmeldung hört auf zu funktionieren, sobald die neue verifiziert ist — auf Integrations-Ebene gibt es kein Überlappungsfenster für Anmeldedaten. Greif zur Rotation in dem Rhythmus, den deine Sicherheitsrichtlinie vorgibt, oder wann immer das Upstream-System meldet, dass die Anmeldung kompromittiert ist. ## Eine Integration einschränken Über die Anmeldedaten hinaus trägt eine Integration zwei Eingrenzungs-Hebel unter ihrer Zeile: - **Erlaubte Rollen.** Schränke ein, welche Rollen-Agents und -Workflows die Integration aufrufen dürfen. Standard ist jede schreibende Rolle (Redakteur, Entwickler, Admin, Inhaber); das einzuengen ist die Art, wie du etwa die Twilio-Integration aus Mitglieder-Agents fernhältst. - **Erlaubte Teams.** Schränke ein, welche Team-Agents und -Workflows die Integration aufrufen dürfen. Nützlich, wenn die Anmeldung zur Arbeit eines Teams gehört (das Slack des Supports) und du nicht willst, dass es in ein anderes leakt. Beide Hebel werden zur Anfrage-Zeit erzwungen, nicht zur Installations-Zeit — ein Hebelwechsel greift beim nächsten Aufruf. ## Eine Integration widerrufen Klick auf die Zeile, dann auf **Trennen**. Eine getrennte Integration hört sofort auf zu authentifizieren; Agents und Workflows, die von ihr abhängen, melden beim nächsten Aufruf einen Konfigurationsfehler. Die Zeile bleibt mit einem Getrennt-Badge in der Liste, damit der Audit-Pfad überlebt. Erneutes Verbinden geht den Anmelde-Fluss von Grund auf neu. ## Slack-Bot und Benachrichtigungen Slack ist zweigerichtet. Über den Agent, der Slack aufruft (Nachrichten posten, Kanäle lesen), hinaus kann die Organisation Leute aus Slack heraus mit einem Agent sprechen lassen und System-Events in einen Kanal pushen. Beides wird auf der verbundenen Slack-Zeile konfiguriert, und beides nutzt dieselbe OAuth-Anmeldung — keine zweite Verbindung. Jede Organisation bringt ihre eigene Slack-App mit, vollständig über die Slack-Zeile konfiguriert — auf dem Deployment ist nichts zu setzen. Wenn du Slack verbindest, zeigt die Zeile ein Panel **Slack-App einrichten** mit einem fertig einfügbaren App-Manifest und den beiden URLs, auf die es verweist: die Request-URL für Event Subscriptions (`/api/integrations/slack/events`) und die OAuth-Redirect-URL. Das Manifest füllt die Bot-Berechtigungen, die Events `app_mention` und `message.im` sowie beide URLs vor, sodass das Erstellen der App auf api.slack.com/apps nur ein paar Klicks dauert. Füge **Client-ID**, **Client-Secret** und **Signing-Secret** der App zurück in die Zeile ein und autorisiere dann per OAuth. Das Signing-Secret verifiziert eingehende Events, also bleibt der Bot stumm, bis es gesetzt ist; eingehende Nachrichten werden über den Slack-Workspace zurück an die richtige Organisation geroutet. Auf der verbundenen Slack-Zeile wählt ein Admin, **welcher Agent auf Slack antwortet** (eine Erwähnung in einem Kanal oder eine Direktnachricht startet eine Thread-Antwort dieses Agents) und **welche Kanäle Benachrichtigungen erhalten**, mit einem Schalter pro Event. Die ausgelieferten Events sind Workflow fehlgeschlagen, Workflow abgeschlossen und Sicherheitswarnungen; ein Slack-Thread bildet sich auf ein Agent-Gespräch ab, und der Slack-Autor bleibt darauf erhalten, statt als System verbucht zu werden. ## Integrationen versus MCP-Server Zwei Oberflächen lassen einen Agent über Tale hinausgreifen. **Integrationen** sind die hier dokumentierten anbieterspezifischen Erstanbieter-Konnektoren. **MCP-Server** sind externe Prozesse, die das Model Context Protocol freilegen; die Organisation registriert sie unter **Einstellungen > MCP-Server** und genehmigt jedes Tool beim ersten Aufruf. Greif zu einer Integration, wenn eine für das Zielsystem existiert; greif zu [MCP-Servern](/de/platform/integrations/mcp-servers), wenn keine Integration deckt, was du brauchst. ## Wo das hingehört Integrationen sind die Anmelde-Hälfte der Agent-zu-Aussenwelt-Geschichte; die Agent-Hälfte (welche Tools ein Agent bekommt, wie er sie aufruft, wie die Vertrauensgrenze aussieht) liegt unter [Agent-Tools](/de/platform/agents/tools). Die natürliche nächste Lektüre für einen neuen Admin ist [Integrations-Übersicht](/de/platform/integrations/overview) — sie nennt jede ausgelieferte Integration nach Zweck gruppiert und gibt das Per-Integrations-Setup auf einen Blick. # API-Schlüssel Source: https://tale.dev/docs/de/platform/admin/api-keys API-Schlüssel sind die organisationsweiten Anmeldedaten, die Tale ausstellt, damit externer Code seine REST-API ohne Person in der Schleife aufrufen kann. Ein Schlüssel authentifiziert den Aufrufer als die Organisation, begrenzt durch die Rolle, die du beim Anlegen wählst. Admins und Entwickler verwalten Schlüssel; andere Rollen sehen die Seite nicht. Das ist die Referenz dafür, was ein Schlüssel ist, wie du einen erstellst, wie du ihn begrenzt und wie du ihn außer Dienst stellst, ohne etwas zu zerbrechen, das von ihm abhängt. Die hier gelisteten Schlüssel sind etwas anderes als die Per-Benutzer-Session-Tokens, die Tale beim Anmelden ausstellt. Die sind kurzlebig und an eine Person gebunden; API-Schlüssel sind langlebig und an die Organisation gebunden. Greif zu einem API-Schlüssel, wenn du ein Skript, einen Cron-Job, einen internen Dienst oder eine Drittanbieter-Integration an Tale anschließt; greif zur In-Produkt-Oberfläche, wenn eine Person an der Tastatur sitzt. <Frame caption="Einstellungen > API-Schlüssel — wo Schlüssel erstellt, rotiert und widerrufen werden."> ![Die REST-API-Schlüssel-Einstellungsseite listet zwei Schlüssel, jeder nur mit seinem Präfix, dem Datum unter Hinzugefügt und der Markierung Nie verwendet, neben der Schaltfläche API-Schlüssel erstellen.](/images/get-started/settings-api-keys.webp) </Frame> ## Einen Schlüssel erstellen Öffne **Einstellungen > API-Schlüssel** und klick auf **API-Schlüssel erstellen**. Gib dem Schlüssel einen Namen, der sagt, wer oder was ihn nutzt (`Billing-Sync`, `Slack-Relay`, `ops-cron`), wähl die Rolle, die er tragen soll, und wähl das Ablaufdatum. Tale zeigt das Geheimnis genau einmal bei der Erstellung — kopier es in deinen Passwort-Manager oder dein Deployment-System, bevor du den Dialog schließt. Danach ist nur noch das Präfix des Schlüssels in der Tabelle sichtbar. Die Rolle, die du wählst, begrenzt alles, was der Schlüssel tun kann. Ein Schlüssel mit Entwickler-Rolle kann jede Ressource lesen und in die meisten schreiben; ein Schlüssel mit Mitglied-Rolle kann die Wissensdatenbank lesen und Chats starten, aber nichts konfigurieren. Nimm die kleinste Rolle, die den Job erledigt — Schlüssel sind genau so gefährlich wie die Rolle, die sie tragen. ## Was die Tabelle zeigt Die API-Schlüssel-Tabelle listet jeden Schlüssel mit Name, Präfix, Rolle, Ersteller, Zeitstempel der letzten Nutzung und Ablauf. Das Präfix sind die ersten acht Zeichen des Geheimnisses — genug, um den Schlüssel in Logs zu identifizieren, ohne ihn offenzulegen. Der Zeitstempel der letzten Nutzung aktualisiert sich bei jeder erfolgreichen Anfrage, die der Schlüssel macht; ein Schlüssel, der wochenlang ungenutzt war, ist meist sicher auszumustern. Die Filterzeile lässt dich nach Rolle, Ersteller und Ablaufzeitraum einengen. Die Standardsortierung ist „zuletzt erstellt zuerst"; die sekundäre Sortierung ist „zuletzt genutzt". ## Einen Schlüssel rotieren Zum Rotieren erstellst du zuerst den neuen Schlüssel, deployst ihn auf das System, das den alten nutzt, prüfst, dass der neue funktioniert (der Zeitstempel der letzten Nutzung aktualisiert sich), und widerrufst erst dann den alten. Tale rotiert Schlüssel nicht automatisch; die Disziplin der Überlappung liegt bei dir. Rotation ist die richtige Bewegung, wenn ein Verdacht auf Leck besteht, wenn jemand mit Zugriff auf den Schlüssel die Organisation verlässt, oder in dem Rhythmus, den deine Sicherheitsrichtlinie vorgibt. ## Einen Schlüssel widerrufen Klick auf die Zeile, dann auf **Widerrufen**. Ein widerrufener Schlüssel authentifiziert sofort nicht mehr — jede laufende Anfrage wird abgeschlossen, aber die nächste schlägt mit `401` fehl. Widerrufene Schlüssel bleiben für den Audit-Pfad in der Tabelle; die Zeile markiert sie als widerrufen und zeigt, wer wann widerrufen hat. Es gibt kein Undo für einen Widerruf; wenn du den falschen widerrufen hast, lege einen neuen an. ## Bereiche und Grenzen Jeder Schlüssel trägt die Berechtigungen seiner Rolle zum Zeitpunkt jeder Anfrage, nicht zum Zeitpunkt der Erstellung. Wenn du die Berechtigungen einer Rolle über eine Governance-Richtlinie änderst, erbt jeder Schlüssel mit dieser Rolle die Änderung bei der nächsten Anfrage. Die Rate-Limits der Organisation gelten pro Schlüssel, nicht pro Organisation; ein lauter Schlüssel drosselt keinen ruhigen. Ein Schlüssel kann bei der Erstellung weiter durch eine IP-Allowlist eingeschränkt werden. Die Allowlist nimmt eine kommagetrennte Liste von CIDR-Blöcken; Anfragen außerhalb der Liste schlagen mit `403` fehl. Greif zur IP-Allowlist, wenn das aufrufende System einen stabilen Egress hat und du Tiefenverteidigung willst. ## Wo das hingehört API-Schlüssel sind die Brücke zwischen Tale und externem Code; sie sitzen neben [Integrationen](/de/platform/admin/integrations) (Drittanbieter-Systeme, die Tale aufruft) und [Webhooks](/de/platform/agents/webhook-triggers) (Systeme, die Tale bei Ereignissen aufrufen). Die natürliche nächste Lektüre ist die REST-API selbst — siehe die API-Referenz im Develop-Tab für die Oberfläche, gegen die ein Schlüssel authentifiziert, und siehe [Mitglieder und Rollen](/de/platform/admin/members-and-roles) für die Rollen-zu-Berechtigungen-Karte, die jeder Schlüssel erbt. # KI-Anbieter Source: https://tale.dev/docs/de/platform/admin/providers Einstellungen > KI-Anbieter ist die Oberfläche, an der Tale auf die Modelle trifft, die es bedient. Eine frische Organisation bringt einen verbundenen Anbieter mit — **OpenRouter**, dessen einzelner Key Chat-, Vision-, Embedding-, Transkriptions-, Sprach- und Bildmodelle erreicht — und Admins fügen von hier Anbieter hinzu, bearbeiten oder mustern sie aus. Jede Antwort, die Tale streamt, wird über ein auf dieser Seite aufgelöstes Modell geroutet; sie anzufassen ändert, was der Rest des Produkts kann. <Frame caption="Einstellungen > KI-Anbieter — die verbundenen Anbieter, jeder mit seiner Basis-URL und dem Umfang seiner Modell-Liste."> ![Die KI-Anbieter-Einstellungsseite listet einen verbundenen Anbieter, OpenRouter, mit seiner Basis-URL und 52 Modellen, neben der Schaltfläche Anbieter hinzufügen und den Sync-Steuerungen des Modellkatalogs.](/images/get-started/settings-providers.webp) </Frame> ## Was die Liste zeigt Öffne **Einstellungen > KI-Anbieter** und du landest auf den Anbietern, die die Organisation verbunden hat. Jede Zeile nennt den Anbieter und zeigt, ob sein API-Schlüssel konfiguriert ist. Ein Klick auf eine Zeile öffnet den Drawer des Anbieters: seine Basis-URL und seinen Schlüssel, seine **Standardmodelle** und die **Modelle**-Liste selbst — durchsuchbar, mit den Fähigkeits-Tags, die entscheiden, wo jedes Modell nutzbar ist. Der Drawer ist der Ort, an dem die ganze Anbieter-Arbeit passiert. Die Listenansicht ist bewusst dünn; die Tiefe liegt einen Klick weiter. ## Einen Anbieter hinzufügen Klick **Anbieter hinzufügen**. **Mit einem bekannten Anbieter starten** wählt OpenAI, Anthropic oder OpenRouter und trägt Anbietername und Basis-URL ein — übrig bleibt nur noch dein API-Schlüssel. Änderst du Name oder Basis-URL von Hand, springt die Auswahl zurück auf **Benutzerdefiniert**, den manuellen Weg: Ein Anbieter ist eine **Basis-URL** plus ein **API-Schlüssel** — der eigene Endpunkt eines Direkt-Anbieters, OpenRouter (`https://openrouter.ai/api/v1`) für den breitesten Katalog, oder ein lokaler Ollama- oder vLLM-Server in deinem Netz. Der Schlüssel wird verschlüsselt gespeichert und nur genutzt, um diesen Anbieter aufzurufen. Sobald die Anmeldedaten sitzen, füll die Modell-Liste: **Modelle abrufen** zieht die Liste, die die API des Anbieters meldet, **Modell hinzufügen** deklariert eines von Hand, und — sobald der Modellkatalog der Organisation synchronisiert ist — füllt die Auswahl eines Modells aus dem Katalog in diesem Dialog dessen ID und bekannte Fähigkeiten (Kontextfenster, Pricing, Reasoning), statt sie einzutippen. Kein Modell ist aufrufbar, bevor es mit dem richtigen Fähigkeits-Tag in der Liste des Anbieters steht. Bei OpenAI, Anthropic und OpenRouter bleibt die Basis-URL auch nach dem Anlegen des Anbieters auf den veröffentlichten Endpunkt gesperrt — öffne den Drawer der Zeile, klick auf **Details bearbeiten** unter **Allgemein**, und das Feld erscheint schreibgeschützt mit der Schaltfläche **Basis-URL überschreiben** daneben. Greif zur Überschreibung nur, wenn du den Slug dieses Anbieters auf einen kompatiblen Proxy oder einen anderen Endpunkt desselben Anbieters richten willst; die Basis-URL jedes anderen Anbieters bleibt direkt editierbar, ganz ohne Überschreibung. ## Die Modell-Liste und Fähigkeits-Tags Jedes Modell trägt einen oder mehrere Fähigkeits-Tags — **Chat**, **Vision**, **Embedding**, **Transkription**, **Text-zu-Sprache**, **Bildgenerierung**, **Bildbearbeitung**. Die Tags sind tragend: sie entscheiden, in welchen Pickern ein Modell erscheint und welche Plattform-Fähigkeit es aufrufen darf. Ein Modell ohne passenden Tag erscheint nie dort, wo diese Fähigkeit gebraucht wird. **In Modell-Auswahl ausgeblendet** nimmt ein Modell aus dem Chat-Composer und der Agent-Modellauswahl, lässt es aber für Agents und Workflows, die es schon referenzieren, voll nutzbar. So geht eine abgelöste oder veraltete Version in Rente, ohne die daran gebundenen Agents zu brechen. ## Standardmodelle Die **Standardmodelle**-Karte nennt, welches Modell jede Fähigkeit nutzt, wenn nichts Spezifischeres gebunden ist — der Chat-Default für neue Chats und neue Agents, plus die Vision-, Embedding-, Bildgenerierungs- und Transkriptions-Defaults, die die Hintergrund-Dienste nutzen. Einen Default zu ändern wirkt nur auf neue Objekte; bestehende Chats und Agents behalten das Modell, an das sie gebunden waren. Greif zu den Defaults, wenn du eine neue Modell-Generation organisationsweit ausrollst, ohne jeden Agent neu zu bearbeiten. ## Den Katalog frisch halten Zwei Steuerungen halten den Katalog aktuell, ohne von Hand zu editieren. Die **Modellkatalog**-Karte frischt die Fähigkeiten jedes Modells — Pricing, Kontextfenster, Reasoning, Vision — täglich aus OpenRouters öffentlichem Katalog auf. Der Schalter **Wöchentliche Auto-Synchronisierung der Anbieter-Konfiguration** mergt neu veröffentlichte Flaggschiff-Versionen einmal pro Woche in die Anbieter-Konfiguration der Organisation, blendet abgelöste aus und lässt jedes Feld, das du angepasst hast, unberührt. ## Wo das hingehört Anbieter sind der Boden des Stacks — jeder Agent, jeder Chat, jeder Workflow-Schritt, der Text erzeugt, löst über sie auf. Der Katalog dessen, was jeder Anbieter ausliefert und welche Tags er trägt, liegt in [Modelle](/de/platform/models); die dateibasierte Form derselben Konfiguration liegt unter [Konfiguration → Provider](/de/self-hosted/configuration/providers); und [Agent-Konzepte](/de/platform/agents/concepts) behandelt, wie der Modell-Knopf in das Vier-Knöpfe-Modell passt, aus dem ein Agent gebaut wird. # Zwei-Faktor-Authentifizierung Source: https://tale.dev/docs/de/platform/admin/two-factor-authentication Zwei-Faktor-Authentifizierung legt einen zweiten Identitätsbeweis über das Passwort — einen sechsstelligen Code aus einer Authenticator-App oder einen WebAuthn-Passkey. Tale bringt TOTP (zeitbasierte Einmal-Passwörter) mit, kompatibel zu Google Authenticator, 1Password, Authy und jeder anderen App, die dem Standard folgt, plus Passkeys als phishing-resistente Alternative. Die Seite deckt die Pro-Benutzer-Registrierung ab, Passkeys, die Backup-Codes, die einen Account wiederherstellen, wenn das Telefon weg ist, die organisationsweite Erzwingungsrichtlinie und das Admin-Reset für ein ausgesperrtes Mitglied. Zwei-Faktor ist standardmäßig optional. Admins können sie für die ganze Organisation verpflichtend machen, mit einem Karenzfenster, damit Mitglieder Zeit zum Einrichten haben. ## Pro-Benutzer-Registrierung Um 2FA für deinen eigenen Account einzuschalten, öffne **Konto > Sicherheit**. Klick auf **Zwei-Faktor aktivieren**, bestätige dein Passwort und scanne den QR-Code mit einer Authenticator-App. Tippe den sechsstelligen Code ein, den die App zeigt, um zu prüfen, dass das Geheimnis aufgenommen wurde, und sichere dann die Backup-Codes, die der nächste Bildschirm zeigt. Die Codes erscheinen einmal — lade oder kopiere sie, bevor du auf **Fertig** klickst. Derselbe Bildschirm trägt **Deaktivieren** und **Backup-Codes neu erzeugen**. Deaktivieren entfernt den zweiten Faktor; Neu-Erzeugen entwertet jeden vorherigen Backup-Code. Beide Aktionen verlangen das Account-Passwort zur Bestätigung. ## Backup-Codes Backup-Codes sind einmal verwendbare Strings, die die Plattform prägt, wenn 2FA aktiviert oder neu erzeugt wird. Jeder davon ersetzt den Authenticator-Code bei einem einzelnen Sign-in — nützlich, wenn das Telefon verloren ist, der Authenticator deinstalliert wurde oder du irgendwo ohne das Gerät feststeckst. Die Plattform beobachtet die verbleibende Anzahl und zeigt ein Niedrig-Banner, wenn nur noch wenige Codes übrig sind; das Banner verlinkt direkt auf den Neu-Erzeugen-Flow. Behandle Backup-Codes wie Passwörter. Lege sie in einen Passwort-Manager oder drucke sie und schließe sie weg. Wer dein Passwort und einen Backup-Code hat, kann sich als du anmelden. ## Passkeys Ein Passkey ist ein WebAuthn-Credential — Face ID, Touch ID, Windows Hello oder ein Hardware-Security-Key —, das bei jeder Anmeldung eine Challenge signiert, statt einen getippten Code zu liefern. Das Credential ist an die Origin der Site gebunden; eine täuschend ähnliche Phishing-Domain bekommt nichts, was sie wiederverwenden könnte. Ein Passkey ist dadurch phishing-resistent auf eine Art, die TOTP nicht erreicht, und er erfüllt eine erzwungene Zwei-Faktor-Richtlinie genau wie TOTP. Zum Registrieren öffne **Konto > Sicherheit** und klick auf **Passkey hinzufügen**. Gib dem Credential einen Namen, den du später wiedererkennst, und wähle den **Authenticator-Typ**: **Beliebig (empfohlen)** lässt den Browser alles anbieten, was verfügbar ist, **Dieses Gerät (Face ID, Touch ID, Windows Hello)** beschränkt die Zeremonie auf den eingebauten Authenticator, und **Security-Key oder Smartphone** auf einen externen. Den Rest erledigt der Browser mit der Registrierungszeremonie. Jeder Eintrag in derselben Liste trägt eine **Entfernen**-Schaltfläche (Symbol) zum Widerrufen deiner eigenen Credentials; sie fragt vor dem Entfernen des Passkeys nach einer Bestätigung. Ein registrierter Passkey funktioniert an drei Türen. Auf dem Login-Bildschirm meldet dich **Mit einem Passkey anmelden** ohne Passwort an — das Credential ist selbst ein starker Nachweis. Auf dem Bestätigungs-Bildschirm nach einem Passwort-Login ersetzt **Stattdessen einen Passkey verwenden** den sechsstelligen Code. Und auf dem Registrierungs-Bildschirm, zu dem eine erzwungene Richtlinie nicht registrierte Mitglieder leitet, sitzt **Stattdessen einen Passkey registrieren** neben der TOTP-Einrichtung — ein Mitglied, das nur einen Passkey registriert und nie TOTP, besteht die Richtlinie. Verliert ein Mitglied ein Gerät mit einem Passkey darauf, widerruft ein Admin das Credential: Öffne **Einstellungen > Organisation**, klick beim Mitglied auf **Mitglied bearbeiten** und entferne das Credential im Abschnitt **Passkeys** des Dialogs. Tale löscht das Credential und beendet jede aktive Sitzung des Mitglieds, sodass ein verlorener oder gestohlener Authenticator keine Sitzung am Leben hält. Registrierung, Selbst-Entfernen, Admin-Widerruf und jede Passkey-Anmeldung landen im Audit-Log (`passkey_added`, `passkey_removed`, `passkey_revoked_by_admin`, `passkey_sign_in`). ## Die Erzwingen-für-Org-Richtlinie Admins können Zwei-Faktor für jedes passwortauthentifizierte Mitglied der Organisation verpflichtend machen. Öffne **Einstellungen > Richtlinien > Sicherheit & Überwachung** und schalte unter **Zwei-Faktor-Authentifizierung** die Option **Zwei-Faktor-Authentifizierung verlangen** ein. Die Richtlinie trägt eine Karenzzeit (in Tagen), die jedem Mitglied vom ersten Sign-in unter der Richtlinie an Zeit zur Registrierung gibt; setz sie auf null für sofortige Erzwingung. <Frame caption="Governance > Sicherheit & Überwachung — Limits für Anmeldeversuche und Passwort-Richtlinie; die Richtlinie für die Zwei-Faktor-Authentifizierung sitzt weiter unten auf derselben Seite."> ![Die Governance-Seite Sicherheit & Überwachung zeigt die Felder für die Limits der Anmeldeversuche und die Zeichenklassen-Anforderungen der Passwort-Richtlinie; die Zwei-Faktor-Richtlinie steht weiter unten auf derselben Seite.](/images/platform/governance-security-monitoring.webp) </Frame> | Feld | Typ | Pflicht | Beschreibung | | --------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Zwei-Faktor-Authentifizierung verlangen | Schalter | ja | Aus hält 2FA für jedes Mitglied optional; ein schaltet die Richtlinie an. | | Karenzzeit (Tage) | Ganzzahl | ja | Tage ab dem ersten angemeldeten Moment eines Mitglieds unter der Richtlinie, bevor die Registrierung verlangt wird. Null heißt sofort. | | Nur-SSO-Benutzer ausnehmen | Schalter | nein | Wenn an, vertrauen Mitglieder, deren einziger Account eine föderierte Identität ist, dem vorgelagerten IdP für MFA. | Ein Mitglied innerhalb des Karenzfensters sieht ein Countdown-Banner in der App, das auf den Registrierungs-Flow zeigt. Sobald die Karenz abläuft, leitet der nächste Sign-in durch den Registrierungs-Bildschirm, und das Mitglied kann erst weiter, nachdem es registriert ist. ## Admin-Reset für ein ausgesperrtes Mitglied Wenn ein Mitglied sein Telefon und seine Backup-Codes verliert, entfernt ein Admin den zweiten Faktor auf seinem Account. Öffne **Einstellungen > Organisation**, klick beim Mitglied auf **Mitglied bearbeiten** und dann auf **Zwei-Faktor zurücksetzen** im Dialog. Tale deaktiviert 2FA für den Account und beendet jede aktive Sitzung, sodass sich das Mitglied beim nächsten Sign-in neu registriert. Das Zurücksetzen wird im Audit-Log unter `2fa_reset_by_admin` festgehalten. Greif dazu als Wiederherstellungs-Aktion — das Mitglied sollte sich sofort neu registrieren, wenn es wieder drin ist. ## Wo das hingehört Zwei-Faktor sitzt eine Schicht über dem Passwort — gleicher Login-Bildschirm, zweiter Schritt. Paar es mit [Mitglieder und Rollen](/de/platform/admin/members-and-roles) (der Admin, der den zweiten Faktor zurücksetzt, ist derselbe Admin, der den Account verwaltet), mit [Richtlinien und Limits](/de/platform/admin/governance/policies-and-limits) (die Erzwingungsrichtlinie lebt in der Governance-Oberfläche) und mit [Audit-Logs](/de/platform/admin/governance/audit-logs) (jede Registrierung, Deaktivierung und jedes Admin-Reset landet dort). # Token-Quellen Source: https://tale.dev/docs/de/platform/admin/token-sources Einstellungen > Token-Quellen ist für den Fall, dass ein einzelner statischer API-Schlüssel nicht reicht: Statt einen Bring-your-own-key-Agenten an ein einziges Geheimnis zu binden, richtest du ihn auf einen externen Broker, der einen _Pool_ aus Anmeldedaten zurückgibt. Der Agent wählt pro Lauf ein Token und fällt, wenn dieses Token rate-limited oder abgelaufen zurückkommt, auf ein anderes aus demselben Pool zurück — bis zu drei Versuche, bevor der Lauf scheitert. Es ist die Rotations-Schicht unter einem BYO-[External Agent](/de/platform/agents/external-agent), nicht mehr: Managed Agents nutzen weiterhin das Org-Gateway und ignorieren diese Seite vollständig. Diese Seite behandelt die Oberfläche — was die Liste zeigt, die Felder beim Hinzufügen einer Quelle, wie eine Quelle an einen Agenten bindet und was die Rotation zur Laufzeit tatsächlich tut. Das Auth-Geheimnis des Brokers ist hier write-only; seine Datei- und Umgebungsvariablen-Form liegt einen Tab weiter unter der [Self-hosted-Konfigurations](/de/self-hosted/configuration/environment-reference)-Referenz. ## Was die Liste zeigt Öffne **Einstellungen > Token-Quellen** und du landest auf der Tabelle der Quellen, die die Organisation konfiguriert hat. Jede Zeile nennt die Quelle, zeigt ihren Broker-**Endpunkt-URL** und zeigt die Ziel-Umgebungsvariable, unter der die Rotations-Engine das gewählte Token injiziert (für einen Claude-Code-Agenten ist das meist `CLAUDE_CODE_OAUTH_TOKEN`). Die Suche filtert nach Name oder Endpunkt; das **···**-Menü an einer Zeile bearbeitet oder löscht sie, und Zeilen auszuwählen blendet eine Sammellösch-Leiste ein. Eine Quelle ist reine Konfiguration — sie speichert, _wie_ der Broker erreicht und _wie_ seine Antwort gelesen wird, nie die Tokens selbst. Tokens werden bei jedem Agentenlauf frisch vom Broker geholt, sodass die Liste gegenüber dem aktuellen Pool des Brokers nie veraltet. ## Eine Quelle hinzufügen Klick auf **Neue Token-Quelle** und füll das Seitenpanel aus. Das Formular ist in vier Abschnitte gegliedert: - **Identität** — ein `slug` (kleingeschrieben, stabil; er benennt die Konfigurationsdatei und das Geheimnis) und ein **Anzeigename**. - **Verbindung** — die **Endpunkt-URL** des Brokers mit ihrer **HTTP-Methode** und wie Tale sich _gegenüber dem Broker_ authentifiziert: **Keine**, ein **Bearer-Token** oder ein **Eigener Header**. Für Bearer oder Header gibst du das **Broker-Geheimnis** ein. Das Geheimnis ist write-only — es wird nie an den Browser zurückgegeben, daher zeigt das Feld beim Bearbeiten leer und es leer zu lassen behält den gespeicherten Wert. - **Antwort-Zuordnung** — wie die JSON-Antwort des Brokers gelesen wird. **Tokens-Pfad** ist ein JSONPath zum Array der Tokens (z. B. `$.tokens`); **Token-Feld** benennt die Eigenschaft, die jedes Token hält. Das optionale **Statusfeld (optional)** / **Aktiver Statuswert (optional)** filtert inaktive Tokens heraus, und **Ablauffeld (optional)** (ein ISO-Zeitstempel oder Epoch-Sekunden/-ms) verwirft bereits abgelaufene, bevor der Pool genutzt wird. - **Einbindung** — die **Ziel-Umgebungsvariable**, unter der das Token injiziert wird, und die **Auswahlstrategie**: **Zufällig** (der Default, wählt pro Lauf gleichverteilt) oder **Erste** (deterministisch). Drück vor dem Speichern auf **Broker testen** im Abschnitt Antwort-Zuordnung: Tale ruft den Broker serverseitig mit der Entwurfskonfiguration ab und zeigt eine Vorschau der Zuordnung — wie viele nutzbare Tokens die Pfade liefern, wie viele Einträge als inaktiv, abgelaufen oder ohne Token-Feld aussortiert wurden und wann das nächste Token abläuft. So fällt ein falscher JSONPath schon im Formular auf statt erst zur Laufzeit des Agenten. Das Speichern validiert die Konfiguration, schreibt sie und macht die Quelle sofort im Umgebungs-Tab des Agenten auswählbar. ## Eine Quelle an einen Agenten binden Eine Token-Quelle tut nichts, bis ein Agent aus ihr zieht. Öffne den **Umgebung**-Tab des Agenten, füg eine Zeile hinzu und ändere ihren Typ von **Wert** / **Geheim** auf **Token-Quelle** — ein zweites Dropdown lässt dich dann wählen, welche Quelle. Der Variablenname der Zeile ist die Umgebungsvariable, in der das gewählte Token landet, und überschreibt für diesen Agenten den eigenen Default der Quelle. Die Bindung greift nur für Bring-your-own-key-Agenten. Ein Managed Agent authentifiziert sich über das Org-Gateway, daher wird eine Token-Quellen-Zeile an ihm mit einer Warnung ignoriert, statt stillschweigend zu ändern, wie der Agent abgerechnet wird. ## Was die Rotation zur Laufzeit tut Wenn ein gebundener BYO-Agent startet, holt Tale den Broker-Pool, filtert inaktive und abgelaufene Tokens heraus und injiziert eine Auswahl. Endet der Lauf in einem rotierbaren Fehler — einem Rate-Limit (`429`/`529`) oder einem Auth-Fehler (`401`/`403`) — tauscht Tale ein anderes Token aus dem Pool ein und lässt erneut laufen, bis zu drei Tokens insgesamt, solange genug vom Lauf-Fenster übrig ist. Ein Auth-Fehler wird früh abgebrochen, statt ihn die internen Retries des Anbieters durchstürmen zu lassen. Scheitert jedes versuchte Token auf dieselbe Weise, scheitert der Lauf schnell mit einem klaren Fehler, statt zu schleifen. Ist der Broker nicht erreichbar, gibt fehlerhaftes JSON zurück oder liefert kein aktives, unabgelaufenes Token, scheitert der Lauf sofort — es gibt keinen stillen Fallback auf einen statischen Schlüssel, weil ein BYO-Agent keinen hat. ## Eine Quelle entfernen Öffne das **···**-Menü und wähl **Löschen**, oder wähl Zeilen aus und nutz die Sammellösch-Leiste. Das Löschen entfernt die Konfiguration und ihr gespeichertes Geheimnis. Jeder Agent, der noch an die gelöschte Quelle gebunden ist, scheitert bei seinem nächsten Lauf mit einem Konfigurationsfehler, statt zurückzufallen, also richte die Bindung im Umgebungs-Tab des Agenten zuerst um oder entferne sie. ## Wo das hingehört Token-Quellen sitzen neben den [KI-Anbietern](/de/platform/admin/providers) als der zweite Weg, auf dem Tale Modell-Anmeldedaten beschafft: Anbieter sind der managed, über das Gateway geroutete Pfad; Token-Quellen sind der BYO-, über den Broker rotierte Pfad für Agenten, die ihre eigenen Schlüssel mitbringen. Die natürliche nächste Lektüre ist die [External-Agent](/de/platform/agents/external-agent)-Seite dafür, wie ein BYO-Agent gebaut wird, und die [Umgebungsreferenz](/de/self-hosted/configuration/environment-reference) für die `TALE_TOKEN_SOURCE_`-Form des Broker-Geheimnisses, wenn du eine Quelle aus Dateien statt aus der UI konfigurierst. # Enterprise-SSO und Bereitstellung Source: https://tale.dev/docs/de/platform/admin/enterprise-sso Mit Enterprise-SSO melden sich deine Mitglieder über deinen Identitätsanbieter (IdP) an, statt mit einem Tale-Passwort, und SCIM lässt den IdP Mitglieder und Gruppen automatisch anlegen, aktualisieren und deaktivieren — ohne manuelle Einladungen. Eine Verbindung pro Organisation trägt das Anmeldeprotokoll, die Bereitstellungsrichtlinie und das SCIM-Token gemeinsam. Alles liegt auf einer Seite: **Einstellungen > Enterprise-SSO** (nur Administratoren). Tale spricht vier Protokolle: **OIDC**, einfaches **OAuth2**, **SAML 2.0** für die Anmeldung und **SCIM 2.0** für die Bereitstellung. Du kannst Anmeldung, Bereitstellung oder beides aktivieren. <Frame caption="Einstellungen > Enterprise-SSO — Protokoll-Auswähler und Anmeldefelder auf einer Seite; die Redirect-URL zum Registrieren im IdP steht bereit zum Kopieren."> ![Die Einstellungsseite Enterprise-SSO mit dem Protokoll-Dropdown auf Microsoft Entra ID und passendem Anzeigename, dazu ein Anmeldebereich mit der zu registrierenden Redirect-URL, einer Issuer-URL und einer Client-ID aus der App-Registrierung, einem leeren Client-Secret und den angeforderten Scopes.](/images/platform/settings-enterprise-sso.webp) </Frame> ## Protokoll wählen Öffne **Einstellungen > Enterprise-SSO**, wähle ein **Protokoll** und fülle nur die Felder dieses Protokolls aus — die übrigen bleiben ausgeblendet. Ein **Einrichtungsleitfaden** auf derselben Seite listet die genauen Schritte auf und zeigt die URLs, die du in deinen IdP einfügst. Verwende **Verbindung testen** vor dem Speichern, um die Konfiguration zu prüfen, und **Speichern**, um die Anmeldung zu aktivieren. - **Microsoft Entra ID** — Microsofts OIDC, mit Gruppe-zu-Team-Synchronisierung über Microsoft Graph. - **Generisches OIDC** — jeder OpenID-Connect-Anbieter (Google, Okta, Auth0, Keycloak, …). Endpunkte werden vom Issuer erkannt. - **OAuth2** — Anbieter ohne OIDC-Discovery; Autorisierungs-, Token- und Userinfo-Endpunkt konfigurierst du manuell. - **SAML 2.0** — XML-basiertes SSO; du tauschst Metadaten mit dem IdP aus. ## Microsoft Entra ID 1. Melde dich im [Microsoft Entra Admin Center](https://entra.microsoft.com) mindestens als Anwendungsentwickler an. 2. Geh zu **Entra ID > App-Registrierungen > Neue Registrierung**, benenne sie und wähle **Einzelner Mandant**. 3. Wähle unter **Umleitungs-URI** die Plattform **Web**, füge die auf der Tale-Seite angezeigte **Weiterleitungs-URL** ein und klicke auf **Registrieren**. 4. Kopiere auf der **Übersicht** die **Anwendungs-(Client-)ID** und die **Verzeichnis-(Mandanten-)ID**. Deine Issuer-URL lautet `https://login.microsoftonline.com/{tenant-id}/v2.0`. 5. Öffne **Zertifikate & Geheimnisse > Neues Clientgeheimnis** und kopiere den **Wert** des Geheimnisses (nicht die Geheimnis-ID). 6. Wähle in Tale **Microsoft Entra ID** und gib Client-ID, Clientgeheimnis und Issuer-URL ein. 7. Für die Gruppe-zu-Team-Synchronisierung füge unter **API-Berechtigungen** die Microsoft-Graph-Berechtigung **GroupMember.Read.All** hinzu und erteile die Administratorzustimmung. 8. Für die OneDrive- und SharePoint-Dokumentensynchronisation füge unter **API-Berechtigungen** die Microsoft-Graph-Berechtigungen **Files.Read** und **Sites.Read.All** hinzu und erteile die Administratorzustimmung. Eine neue Verbindung fordert beide standardmäßig an — das SSO-Token dient zugleich als Graph-Token, Mitglieder können also direkt nach der Anmeldung Dateien importieren. Soll die Organisation nur die Anmeldung nutzen, entferne die beiden Scopes aus dem Feld **Scopes**; der Microsoft-365-Eintrag bleibt dann auf der Dokumentenseite verborgen. ## Google Google wird als generischer OIDC-Anbieter konfiguriert. 1. Öffne in der [Google Cloud Console](https://console.cloud.google.com) **APIs & Dienste > Anmeldedaten > Anmeldedaten erstellen > OAuth-Client-ID**. 2. Wähle den Anwendungstyp **Webanwendung**. 3. Füge unter **Autorisierte Weiterleitungs-URIs** die auf der Tale-Seite angezeigte **Weiterleitungs-URL** hinzu und speichere. 4. Kopiere **Client-ID** und **Clientgeheimnis** oben auf der Client-Seite. 5. Wähle in Tale **Generisches OIDC**, gib Client-ID und Geheimnis ein und setze die Issuer-URL auf `https://accounts.google.com`. Die Endpunkte werden automatisch erkannt. Das Standard-OIDC von Google liefert **keine** Gruppenmitgliedschaften, daher ist die Gruppe-zu-Team-Synchronisierung mit Google allein nicht verfügbar — sie benötigt das Admin SDK / die Cloud Identity API mit einem Workspace-Administrator. Anmeldung und Rollenzuordnung per Claim funktionieren normal. ## Generisches OIDC und OAuth2 Für jeden anderen OIDC-Anbieter (Okta, Auth0, Keycloak) wähle **Generisches OIDC**, füge die **Issuer-URL** sowie Client-ID/Geheimnis ein — Tale liest die Autorisierungs-, Token- und Userinfo-Endpunkte aus dem `.well-known/openid-configuration` des Issuers. Wenn ein Anbieter OAuth2, aber kein Discovery-Dokument bietet, wähle **OAuth2** und gib die URLs für **Autorisierungs-**, **Token-** und **Userinfo**-Endpunkt manuell ein. Verwendet der Anbieter abweichende Claim-Namen, ordne **E-Mail**, **Name** und **Gruppen** in den erweiterten Feldern der Verbindung zu (Dot-Pfade werden unterstützt, z. B. `realm_access.roles`). ## SAML 2.0 1. Wähle in Tale **SAML 2.0**. Die Seite zeigt deine **SP-Metadaten-URL** und **ACS-URL (Antwort)** — kopiere diese. 2. Erstelle in deinem IdP eine neue SAML-2.0-Anwendung. Setze deren **ACS-URL** und **Entity-ID/Audience** auf die angezeigten SP-Werte (oder lade die SP-Metadaten-URL hoch) und das **Name-ID**-Format auf E-Mail-Adresse. 3. Füge unter **IdP-Metadaten importieren** die Föderations-Metadaten-URL deines IdP ein und klick auf **Importieren** — oder klick auf **XML hochladen**, falls dein IdP nur eine Datei zum Herunterladen anbietet. Tale liest die Metadaten aus und füllt Entity-ID, Anmelde-URL und Signaturzertifikat in den Feldern darunter, ohne dass du etwas abtippen musst. Alle drei Felder bleiben bearbeitbar — prüfe die importierten Werte (oder trag sie von Hand ein, falls dein IdP keine Metadaten veröffentlicht), bevor du speicherst. 4. Ordne die Attribute für **E-Mail**, **Name** und **Gruppe** in deinem IdP zu; weichen die Namen von den Standardwerten ab, trage die passenden Attributnamen in Tales erweiterten Feldern ein. Tale unterstützt sowohl IdP-initiiertes SAML (der IdP sendet eine Assertion an die ACS-URL) als auch SP-initiiertes SAML (ein Mitglied klickt auf **Mit SSO anmelden** und Tale leitet zum IdP weiter). Signierte Assertions sind erforderlich; verschlüsselte Assertions werden unterstützt, wenn du ein SP-Schlüsselpaar bereitstellst. ## Mehrere Organisationen auf einem Deployment Ein Deployment kann mehrere Organisationen mit jeweils eigener Verbindung beherbergen. Klicke auf der Anmeldeseite auf **Weiter mit SSO** und wähle deine Organisation aus der Liste — jeder Eintrag zeigt den **Anzeigenamen** der Verbindung. Dieser Name ist auf der Anmeldeseite für alle sichtbar; setze in **Einstellungen > Enterprise-SSO** pro Verbindung einen klaren Anzeigenamen. ## Bereitstellung: Rollen und Teams Jedes Protokoll teilt sich eine Bereitstellungsrichtlinie: - **Standardrolle** — die Rolle, die ein neu bereitgestelltes Mitglied erhält (standardmäßig Mitglied). - **Rollen automatisch zuweisen** — wenn aktiv, ordnen Rollenregeln einen Jobtitel, eine App-Rolle, eine Gruppe oder einen Claim einer Plattformrolle zu; trifft nichts zu, gilt die Standardrolle. - **Gruppen mit Teams synchronisieren** — wenn aktiv, wird jede IdP-Gruppe des Benutzers bei der Anmeldung zu einem gleichnamigen Team (oder tritt ihm bei); **Gruppen ausschließen** überspringt störende Gruppen (kommagetrennt). ## SCIM-Bereitstellung (Benutzer und Gruppen) Mit SCIM überträgt dein IdP Änderungen, ohne dass sich jemand anmelden muss. Klicke im Abschnitt **SCIM-Bereitstellung** auf **Token generieren** — kopiere es einmalig (es wird nicht erneut angezeigt) — und füge es zusammen mit der angezeigten **SCIM-Basis-URL** in die Bereitstellungseinstellungen deines IdP ein. Der IdP authentifiziert sich mit dem Token als Bearer-Anmeldedaten; Tale ermittelt die Organisation aus dem Token, das damit die Mandantengrenze bildet. Tale implementiert SCIM 2.0 **Users** und **Groups**: anlegen, lesen, auflisten (mit `userName`/`displayName`-Filtern), ersetzen, patchen und löschen. Bereitgestellte Benutzer entsprechen Organisationsmitgliedern, Gruppen entsprechen Teams. **Die Deaktivierung ist sanft** — setzt der IdP einen Benutzer inaktiv (`active: false`), wird die Rolle des Mitglieds auf `disabled` gesetzt (was den Zugriff entzieht), und eine Reaktivierung stellt die vorherige Rolle wieder her. Ein SCIM-**Löschen** entfernt die Mitgliedschaft aus der Organisation; das Benutzerkonto selbst bleibt bestehen, und eine erneute Bereitstellung fügt es mit der Standardrolle der Verbindung wieder hinzu. Der Inhaber der Organisation kann über SCIM nie entfernt werden. ## Überprüfung Verwende **Verbindung testen** für OIDC/OAuth2, um Discovery und Anmeldedaten vor dem Speichern zu bestätigen. Für SAML lade die SP-Metadaten in deinen IdP und führe eine Testanmeldung durch. Für SCIM bieten die meisten IdPs eine „Test"- oder „Jetzt bereitstellen"-Aktion, die einen Beispielbenutzer anlegt — prüfe, ob er unter **Einstellungen > Mitglieder** erscheint. Eine End-to-End-SSO-Anmeldung prüfst du am besten gegen deinen echten IdP in einer Staging-Organisation. # Modellkatalog Source: https://tale.dev/docs/de/platform/models Jeder Modell-Picker in Tale — das Modellmenü des Composers, die Modellbindung eines Agents, die Standards, die Crawler- und RAG-Dienste nutzen — zieht aus einem Katalog: den Modellen, die auf den KI-Providern deiner Organisation deklariert sind. Eine frische Instanz bringt einen einzigen Provider mit, **OpenRouter**, dessen ein Key Chat, Vision, Embeddings, Transkription, Text-to-Speech und Bildgenerierung abdeckt. Diese Seite ist die Referenz dafür, wo dieser Katalog in der UI liegt, was die Tags auf jedem Modell bedeuten und was ab Werk mitkommt. <Frame caption="Die Modell-Liste im Provider-Drawer — jedes Modell trägt die Fähigkeits-Tags, die entscheiden, in welchen Pickern es erscheint."> ![Der Provider-Detail-Drawer unter Einstellungen > KI-Anbieter, mit einer durchsuchbaren Modell-Liste, in der jede Zeile Fähigkeits-Tags wie Chat und Bildgenerierung trägt, darüber die Aktionen Modelle abrufen, Aus Katalog synchronisieren und Modell hinzufügen.](/images/platform/settings-provider-models.webp) </Frame> ## Wo der Katalog liegt Öffne **Einstellungen > KI-Anbieter** und klick eine Provider-Zeile an. Der Drawer listet alles, was der Provider deklariert: seine Basis-URL und seinen API-Schlüssel, seine **Standardmodelle** und die **Modelle**-Liste selbst — durchsuchbar, mit **Mehr anzeigen** hinter den ersten zehn. **Modell hinzufügen** deklariert einen neuen Eintrag von Hand; **Modelle abrufen** zieht die Liste, die die API des Providers meldet. Modelle, die ein Admin als **In Modell-Auswahl ausgeblendet** markiert, bleiben für bestehende Bindungen auflösbar, erscheinen aber nicht mehr in Menüs — so gehen abgelöste Versionen in Rente, ohne alte Agents zu brechen. Jedes Modell trägt einen oder mehrere Fähigkeits-Tags: **Chat**, **Vision**, **Embedding**, **Transkription**, **Text-zu-Sprache**, **Bildgenerierung**, **Bildbearbeitung**. Die Tags sind tragend — sie entscheiden, in welchen Pickern ein Modell auftaucht und welche Plattform-Fähigkeit es aufrufen darf. Ein Modell ohne passenden Tag erscheint nie dort, wo diese Fähigkeit gebraucht wird. ## Die ausgelieferten Standards Die **Standardmodelle**-Karte nennt, welches Modell jede Hintergrund-Fähigkeit nutzt, wenn nichts Spezifischeres gebunden ist: | Fähigkeit | Ausgelieferter Standard | | --------------- | ----------------------- | | Chat | DeepSeek V4 Flash | | Vision | Qwen3 VL 32B | | Embedding | Qwen3 Embedding 8B | | Bildgenerierung | FLUX.2 [pro] | | Transkription | Whisper v1 | Text-to-Speech für den [Sprachmodus](/de/platform/chat/voice-mode) kommt über OpenAIs GPT-4o mini TTS über denselben OpenRouter-Key, und [Bildgenerierung](/de/platform/agents/image-generation) fällt auf FLUX.2 [pro] zurück. ## Wie die Liste frisch bleibt Modelle driften schneller als Docs. Zwei Mechanismen auf der Seite **KI-Anbieter** halten den Katalog aktuell: die **Modellkatalog**-Karte frischt Modell-Fähigkeiten — Pricing, Kontextfenster, Reasoning, Vision — täglich aus OpenRouters öffentlichem Katalog auf, und der Schalter **Wöchentliche Auto-Synchronisierung der Anbieter-Konfiguration** mergt neu veröffentlichte Flaggschiff-Versionen einmal pro Woche in die Provider-Konfiguration der Org, blendet abgelöste aus und lässt jedes Feld, das du angepasst hast, unberührt. Die Lieferliste unten wird aus derselben Quelle neu generiert, sie stimmt also mit dem, was eine frische Instanz sieht: <!-- MODELS_TABLE:START --> <!-- Auto-generated from builtin-configs/providers/openrouter.json by the weekly model-catalog sync. Do not edit by hand. --> | Anbieter | Modell | Fähigkeiten | Kontext | Eingabe ($/M) | Ausgabe ($/M) | | ----------------- | ------------------------------------ | ---------------------------- | ------- | ------------- | ------------- | | AI21 | Jamba Large 1.7 | chat | 256K | 2.00 | 8.00 | | Amazon | Nova Premier | chat, vision | 1M | 2.50 | 12.50 | | Amazon | Nova 2 Lite | chat, vision | 1M | 0.30 | 2.50 | | Anthropic | Claude Fable (latest) | chat, vision | 1M | 10.00 | 50.00 | | Anthropic | Claude Fable 5 | chat, vision | 1M | 10.00 | 50.00 | | Anthropic | Claude Sonnet 4.6 | chat, vision | 1M | 3.00 | 15.00 | | Anthropic | Claude Haiku 4.5 | chat | 200K | 1.00 | 5.00 | | Anthropic | Claude Opus 4.8 | chat, vision | 1M | 5.00 | 25.00 | | Black Forest Labs | FLUX.2 [flex] | image-generation, image-edit | — | — | — | | Black Forest Labs | FLUX.2 [max] | image-generation, image-edit | — | — | — | | Black Forest Labs | FLUX.2 [pro] | image-generation, image-edit | — | — | — | | Cohere | Command A | chat | 256K | 2.50 | 10.00 | | Cohere | Command R | chat | 128K | 0.15 | 0.60 | | DeepSeek | DeepSeek V4 Pro | chat | 1M | 0.43 | 0.87 | | DeepSeek | DeepSeek V4 Flash | chat | 1M | 0.09 | 0.18 | | Google | Gemini 3 Pro | chat, vision | 1M | 2.00 | 12.00 | | Google | Gemini 3 Flash | chat, vision | 1M | 0.50 | 3.00 | | Google | Gemma 4 31B IT | chat, vision | 262K | 0.12 | 0.35 | | Google | Gemma 4 26B A4B IT | chat, vision | 262K | 0.06 | 0.33 | | Google | Nano Banana (Gemini 2.5 Flash Image) | image-generation, image-edit | 33K | 0.30 | 2.50 | | Liquid | LFM2 24B | chat | 128K | 0.03 | 0.12 | | Meta | LLaMA 4 Maverick | chat | 1M | 0.15 | 0.60 | | Meta | LLaMA 4 Scout | chat | 10M | 0.10 | 0.30 | | Microsoft | Phi-4 | chat | 16K | 0.07 | 0.14 | | MiniMax | MiniMax M3 | chat, vision | 1M | 0.30 | 1.20 | | Mistral | Mistral Large 3 | chat | 262K | 0.50 | 1.50 | | Mistral | Mistral Medium 3.5 | chat, vision | 262K | 1.50 | 7.50 | | Moonshot AI | Kimi K2.6 | chat, vision | 262K | 0.68 | 3.41 | | Moonshot AI | Kimi K2.7 Code | chat, vision | 262K | 0.61 | 3.07 | | NVIDIA | Nemotron 3 Ultra | chat | 1M | 0.50 | 2.20 | | NVIDIA | Nemotron 3 Super | chat | 1M | 0.09 | 0.45 | | OpenAI | GPT-OSS 120B | chat | 131K | 0.04 | 0.18 | | OpenAI | GPT-4o mini TTS | text-to-speech | — | — | — | | OpenAI | GPT-5.3 Chat | chat, vision | 128K | 1.75 | 14.00 | | OpenAI | GPT-5.5 | chat, vision | 1M | 5.00 | 30.00 | | OpenAI | GPT-5.5 Pro | chat, vision | 1M | 30.00 | 180.00 | | OpenAI | Whisper v1 | transcription | — | — | — | | Perplexity | Sonar Pro | chat, vision | 200K | 3.00 | 15.00 | | Perplexity | Sonar | chat, vision | 127K | 1.00 | 1.00 | | Qwen | Qwen3.6 Max Preview | chat | 262K | 1.04 | 6.24 | | Qwen | Qwen3 Coder 480B | chat | 1M | 0.22 | 1.80 | | Qwen | Qwen3 VL 32B | chat, vision | 262K | 0.10 | 0.42 | | Qwen | Qwen3.6 Flash | chat, vision | 1M | 0.19 | 1.13 | | Qwen | Qwen3 Embedding 8B | embedding | — | 0.01 | 0.00 | | Qwen | Qwen3.7 Plus | chat, vision | 1M | 0.32 | 1.28 | | Reka | Reka Flash 3 | chat | 66K | 0.10 | 0.20 | | Xiaomi | MiMo V2.5 Pro | chat | 1M | 0.43 | 0.87 | | Z.AI | GLM 5.1 | chat | 203K | 0.98 | 3.08 | | Z.AI | GLM 5 Turbo | chat | 262K | 1.20 | 4.00 | | Z.AI | GLM 5V Turbo | chat, vision | 131K | 1.20 | 4.00 | | xAI | Grok 4.20 | chat, vision | 2M | 1.25 | 2.50 | <!-- MODELS_TABLE:END --> Der volle und aktuelle Katalog lebt auf [openrouter.ai/models](https://openrouter.ai/models); jedes Modell, das OpenRouter exponiert, lässt sich aus demselben Drawer zu deiner Instanz hinzufügen. ## Wo das hineinpasst Modelle sind die Schicht unter jedem Agent, jeder Chat-Antwort, jeder Sprachausgabe und jedem Bild, das die Plattform rendert. OpenRouter ist der Default, keine Vorgabe — einen Direkt-Anbieter, einen lokalen Ollama- oder vLLM-Server oder ein zweites Gateway hinzuzufügen ist Admin-Arbeit, die [Provider](/de/platform/admin/providers) abdeckt, und die dateibasierte Form derselben Konfiguration liegt unter [Konfiguration → Provider](/de/self-hosted/configuration/providers). Zum Auswählen zwischen Chat-Modellen, wenn mehr als eines die Arbeit machen könnte, ist [Arena-Modus](/de/platform/chat/arena-mode) der Workflow, der genau für diese Frage gebaut ist. # Redakteur Source: https://tale.dev/docs/de/platform/editor/overview Redakteur ist die Bau-Oberfläche von Tale. Während Mitglied die Rolle ist, die das Produkt nutzt, und Admin die Rolle ist, die es steuert, ist Redakteur die Rolle, die die Dinge erstellt, die alle anderen nutzen — Agents, Projekte, Automatisierungen, die Dokumente und strukturierten Daten, die die Wissensdatenbank hält, die Prompts, die fürs Team gespeichert sind. Personen mit Redakteurs-Rolle sehen das volle Set an Bau-Tabs ohne die Admin-Governance-Oberfläche und ohne die nur-Entwickler-Hebel. Diese Übersicht nennt, was ein Redakteur tut, wo er es tut und welche Seiten jeden Teil abdecken. Redakteure landen typischerweise hier am ersten Tag, bauen den ersten nützlichen Agent und das erste Projekt der Organisation aus und kommen wieder auf diesen Tab, wann immer das Nächste gebaut werden muss. Die Rollen- und Berechtigungs-Geschichte hinter den Tabs liegt auf [Mitglieder und Rollen](/de/platform/admin/members-and-roles). ## Was Redakteur abdeckt Die Arbeit eines Redakteurs fällt in vier Bereiche: **Agents** bauen (Anweisungen, Wissensbindungen, Tools, Modelle), die **Wissensdatenbank** kuratieren (Dokumente hochladen, Kunden, Produkte, Lieferanten, Websites pflegen), **Automatisierungen** verfassen (Workflows mit Triggern, Schritten und Genehmigungs-Gates) und **Projekte** bündeln (Dateimengen, projektgebundene Agents, Projekt-Anweisungen). Jeder davon hat seinen eigenen Ort in Platform; der Redakteurs-Tab ist der Index über sie hinweg. Redakteure teilen die Bau-Oberfläche mit Entwicklern — Entwickler sehen ebenfalls alle vier Bereiche und können alles, was ein Redakteur kann, plus die API- und Integrations-Ebene. Greif zu einem Redakteur, wenn die tägliche Arbeit Inhalt und Konfiguration ist; greif zu einem Entwickler, wenn die Arbeit in Code oder externe Systeme übergeht. ## Seiten in diesem Bereich Die Redakteurs-Oberfläche ist dieselbe Oberfläche, die die Per-Bereich-Sektionen von Platform dokumentieren. Was folgt, ist der Index über sie hinweg. <CardGroup cols="2"> <Card title="Agents" icon="bot" href="/de/platform/agents/concepts"> Das Vier-Knöpfe-Mentalmodell, aus dem ein Redakteur jeden Agent baut. </Card> <Card title="Automatisierungen" icon="workflow" href="/de/platform/automations/concepts"> Workflows, Trigger, Schritte, Ausführungen. </Card> <Card title="Wissen" icon="library" href="/de/platform/knowledge/overview"> Der Dokumente- und Strukturdaten-Bereich, den ein Redakteur kuratiert. </Card> <Card title="Projekte" icon="folder-open" href="/de/platform/projects/overview"> Der geteilte Workspace, den ein Redakteur um einen Kunden oder einen Launch bündelt. </Card> <Card title="Prompt-Bibliothek" icon="list-plus" href="/de/platform/workspace/prompt-library"> Der Bereich für gespeicherte Prompts, in dem ein Redakteur wiederkehrende Chat-Starter wiederverwendbar hält. </Card> </CardGroup> ## Wo das hingehört Redakteur ist die Rolle, von der die meisten Teams mehrere haben — die Personen, die die Bauarbeit machen, die andere Rollen konsumieren. Die natürliche Erstlektüre am ersten Tag ist [Agent-Konzepte](/de/platform/agents/concepts), weil das Vier-Knöpfe-Modell das ist, was jede andere Bau-Seite voraussetzt. Die natürliche Zweite ist [Deinen ersten Agent bauen](/de/tutorials/editor/first-agent-end-to-end) — sie geht die vier Knöpfe Ende zu Ende auf einer frischen Instanz durch. # Selbst gehostete Architektur Source: https://tale.dev/docs/de/self-hosted/overview Eine Tale-Instanz besteht aus acht Containern hinter einem Caddy-Proxy, die mit zwei Postgres-Datenbanken sprechen — einer operativen, einer für den Wissens-Korpus; zwei davon sind Sandbox-Container an der Seite für Code-Ausführung. Die compose-Datei ist der Vertrag — was läuft, was exponiert ist, was gemountet ist. Diese Seite vermittelt das mentale Modell, sodass die Install-, Konfigurations- und Betriebsseiten es nicht erneut erklären müssen. Lies das, bevor du `docker compose up` ausführst. Komm zurück, wenn du einen Ausfall debuggst und wissen musst, welches Container-Log du zuerst öffnen solltest. ## Die acht Container **tale-proxy** ist Caddy am Rand. Er terminiert TLS, leitet alles unter `/` an den Plattform-Container und alles unter `/api/` und die Convex-Pfade an den Convex-Container weiter. Health-Checks leben hier. **tale-platform** ist der React + TanStack Start-Server. Er rendert die UI, liefert statische Assets aus und ist der einzige Container, der dem Browser exponiert ist. Er hält keinen Geschäfts-State — alles, was persistieren muss, spricht mit Convex. **tale-convex** ist das Backend: die Actions, Queries, Mutations und die WebSocket-Schicht, die die UI abonniert. Provider-Keys, Agent-Definitionen, Workflow-Läufe, Audit-Logs — alles davon lebt hier. Es läuft auch die Wissens-Arbeit im Prozess — Dokument-Ingestion, Web-Crawling, RAG-Suche und Dokumentgenerierung sind Convex-Node-Actions, keine separaten Services. Die Headless-Arbeit, die diese Jobs brauchen (eine Webseite rendern, HTML in ein PDF oder Bild verwandeln), wird an die Sandbox-Laufzeit delegiert, die ohnehin schon Chromium und Playwright mitbringt. **tale-db** ist das operative Postgres (ParadeDB). Es hält die Daten des Convex-Backends — Agents, Runs, das Audit-Log — und ist einer der zwei zustandsbehafteten Container, die für Backups zählen. **tale-knowledge-db** ist das Postgres des Wissens-Korpus (ParadeDB), die `tale_knowledge`-Datenbank mit zwei Schemata: `private_knowledge` (Chunks hochgeladener Dokumente, Embeddings, der BM25-Index, der semantische Cache) und `public_web` (gecrawlte Webseiten). Es ist von `tale-db` getrennt, damit der Korpus — der datenresidenz-sensible Speicher — sich für sich allein verlagern oder ersetzen lässt. Das Convex-Backend verbindet sich direkt mit ihm; nichts sonst tut das. **tale-sandbox-llm-gateway** ist das LLM-Gateway für In-Sandbox-Coding-Agents. Es ist der einzige Pfad von einem sandboxierten Agent zu einem Modell-Provider; die Plattform stellt es bereit und prägt Per-Session-Keys. **tale-sandbox** und **tale-sandbox-egress** führen sandboxierten Code für das **Code-ausführen**-Tool und Fähigkeits-Skripte aus und dienen als die Headless-Browser-Laufzeit, die das Convex-Backend für Web-Render und Dokumentgenerierung aufruft. Der Egress-Container ist der einzige Netzwerkweg, den die Sandbox hat. Egress ist standardmäßig offen — sandboxierter Code erreicht jeden öffentlichen Host über HTTPS, Cloud-Metadaten und private Adressbereiche bleiben auf IP-Ebene blockiert. Einschränken kannst du das mit `SANDBOX_EGRESS_ALLOWLIST` auf eine Hostname-Allowlist; die Anleitung steht in [Hardening](/de/self-hosted/operate/security/hardening). Ein weiterer Service kommt mit, bleibt aber standardmäßig aus: **tale-controller** ist ein Opt-in-Sidecar (das `controller`-compose-Profil), der den Convex-Container auf eine signierte Anfrage der App neu startet, damit eine Datenresidenz-Änderung greifen kann, ohne der browserzugewandten Plattform Docker-Socket-Zugriff zu geben. ## Daten auf dem Storage Vier Volumes überleben ein `docker compose down`: - `db-data` — das Datenverzeichnis des operativen Postgres: die Datenbank hinter Agents, Runs und dem Audit-Log. - `knowledge-db-data` — das Datenverzeichnis des Postgres für den Wissens-Korpus: Dokument-Chunks, Embeddings, die Such-Indizes und gecrawlte Webseiten. Sichert separat von `db-data`, weil es eine eigene Datenbank ist. - `backups` — checksummengesicherte Volume-Snapshots, geschrieben von `tale backup` und automatisch vor migrierenden Deploys; [Backups und Restore](/de/self-hosted/operate/backups-and-restore) ist der Drill. - Der Object-Store-Mount von Convex — hochgeladene Dateien, generierte Dokumente, exportierte Bundles. Alles andere ist flüchtig. Container können ohne Datenverlust ersetzt werden, solange die Volumes überleben. ## Provider-Secrets und die SOPS-Schicht Provider-Keys (OpenAI, Anthropic, Azure, Ollama, etc.) leben auf dem Storage in einem `providers/`-Verzeichnis, das in den Plattform-Container gemountet wird. Jeder Provider hat eine `<name>.json` und eine `<name>.secrets.json`; die Secrets-Datei ist mit SOPS und der Variable [`SOPS_AGE_KEY`](/de/self-hosted/configuration/environment-reference) verschlüsselt. Diese Trennung existiert aus zwei Gründen. Einen Provider-Key zu rotieren ist eine Datei zu bearbeiten, nicht die Plattform neu zu starten; die verschlüsselte Datei zu sichern ist sicher, sie neben der Infrastruktur zu committen. Der Klartext-Modus (kein SOPS, Secrets in Klartext) wird für streng kontrollierte Umgebungen unterstützt, wo der Storage selbst at-rest verschlüsselt ist. ## Auth und Sessions Sign-in ist Better Auth, das im Convex-Container läuft. Vier Sign-in-Modi sind dabei: lokales Passwort, Microsoft Entra (OAuth/OIDC), generisches OIDC und Trusted Headers (der Reverse-Proxy liefert die Identität). Der Plattform-Container liest das Cookie, übergibt es an Convex, und Convex entscheidet, was die Session tun darf, basierend auf der Rolle des Benutzers und der Berechtigungs-Matrix pro Ressource, die in [Mitglieder und Rollen](/de/platform/admin/members-and-roles) dokumentiert ist. Die [Authentifizierungs-Referenz](/de/self-hosted/configuration/authentication) behandelt die Umgebungsvariablen und die Trade-offs pro Modus. ## Wenn du Single-Host hinter dir lässt Die Standard-compose-Datei betreibt alle acht Container auf einem Host. Die Architektur ist single-tenant: nichts im Design teilt Arbeit über Hosts hinweg. Das Erste, was du ohne Re-Architektur von der Box bewegen kannst, ist der Wissens-Korpus — `tale-knowledge-db` ist ein eigenständiges Postgres, also ist es eine Connection-String-Änderung, es auf verwaltete Infrastruktur zu zeigen (für Kapazität oder eine Residenz-Anforderung), behandelt in [Datenresidenz](/de/self-hosted/configuration/data-residency). Die Convex-Schicht ist immer noch Single-Instance; horizontale Skalierung des Backends ist kein v1-Feature. ## Wo das hingehört Diese Architektur-Seite ist die Karte, die jede andere selbst-gehostete Seite voraussetzt. Die natürliche nächste Lektüre ist [Quickstart](/de/self-hosted/install/quickstart), wenn du eine frische Instanz aufsetzt, oder [Container-Architektur](/de/self-hosted/operate/container-architecture), wenn du eine betreibst und dasselbe Bild mit den Fehler-Modi überlagert brauchst. # Selbst gehostet Source: https://tale.dev/docs/de/self-hosted Selbst gehostetes Tale läuft auf deiner eigenen Infrastruktur — on-premise, in deiner VPC oder air-gapped. Sieben Container, deine Daten auf deinem Storage, keine Pro-Sitz-Abrechnung und kein Traffic, der zu Tales Servern fließt, außer du richtest einen Anbieter dort ein. Dieser Abschnitt ist für Operator: die Leute, die entscheiden, wo Tale läuft, es installieren, konfigurieren, gepatcht halten und den Pager übernehmen, wenn etwas schiefgeht. Endnutzer von selbst gehosteten Instanzen lesen meist den Reiter Plattform — die Produktoberfläche ist zwischen den Editionen identisch. ## Seiten in diesem Abschnitt **[Architektur-Überblick](/de/self-hosted/overview)** — was jeder Container tut, wo Daten auf dem Storage liegen, was mit was spricht. **[Installation](/de/self-hosted/install/quickstart)** — Quickstart auf dem Laptop, Produktions-Setup auf einem Linux-Host, die docker-compose-Referenz, erstes Admin-Setup, das CLI-Installationsskript. **[Konfiguration](/de/self-hosted/configuration/environment-reference)** — jede Umgebungsvariable, Provider-Dateien, Authentifizierungsmodi, TLS, Speicher, Aufbewahrung, SOPS-verschlüsselte Secrets, Observability. **[Betrieb](/de/self-hosted/operate/container-architecture)** — Upgrades, Backups und Restore, Observability und Troubleshooting, Security-Advisories, Härtung, Format der Release Notes. **[Mitwirken](/de/self-hosted/contributing-docker)** — wie du eine lokale Container-Änderung baust und testest. ## Wo das hingehört Selbst gehostet ist die Edition, in der der Operator mehr vom Stack besitzt. Wenn dein Team klein ist und der Betriebsaufwand die Produktarbeit verdrängen würde, ist [Cloud](/de/cloud) die andere Form desselben Produkts. Wenn du gerade eine frische Instanz aufsetzt, ist [Quickstart](/de/self-hosted/install/quickstart) der richtige nächste Lesestoff. # Zu Docker-Images beitragen Source: https://tale.dev/docs/de/self-hosted/contributing-docker Jeder Container, den Tale ausliefert, hat sein Dockerfile im öffentlichen Quell-Repo. Forks, Air-gapped-Distributionen und einmalige Patches starten alle aus denselben Dateien; diese Seite ist der Operator-Durchgang durch das Selber-Bauen der Images, wo die Anpassungs-Nähte leben und wie du einen Fork mit Upstream synchron hältst, ohne bei den langweiligen Teilen abzudriften. Die Container-Architektur lebt in [Container-Architektur](/de/self-hosted/operate/container-architecture); diese Seite ist das, was du liest, wenn die veröffentlichten Images nicht passen und du deine eigenen bauen musst. ## Was die Images sind Der Stack ist vollständig TypeScript — kein Python-Image. Jedes Image hat ein Dockerfile unter `services/<name>/`: | Image | Quell-Pfad | Basis | | ------------------------ | ----------------------------- | ---------------------------- | | `tale-proxy` | `services/proxy/` | Caddy | | `tale-platform` | `services/platform/` | Bun + Debian slim | | `tale-convex` | `services/convex/` | Convex local-backend | | `tale-db` | `services/db/` | ParadeDB (Postgres) | | `tale-sandbox` | `services/sandbox/` | Bun + Docker-CLI | | `tale-sandbox-egress` | `services/sandbox-egress/` | Alpine + tinyproxy | | `tale-sandbox-runtime` | `services/sandbox-runtime/` | Bun + Chromium + Playwright | | `tale-sandbox-buildkitd` | `services/sandbox-buildkitd/` | Debian + BuildKit + redsocks | | `tale-controller` | `services/controller/` | Bun + Docker-CLI | Beide Datenbank-Container — `db` und `knowledge-db` — bauen aus demselben `tale-db`-ParadeDB-Image; der Unterschied ist die Datenbank, die jeder bedient. Das LLM-Gateway `tale-sandbox-llm-gateway` ist ein gepinntes Upstream-Image (`maximhq/bifrost`), hat also kein Dockerfile im Repo. Die Compose-Dateien im Repo-Root (`compose.yml` für Development, die CLI-generierte Produktions-Compose) referenzieren diese über `ghcr.io/tale-project/tale/<image>:<tag>`. Ein lokaler Build ersetzt den Registry-Pull mit einem `build:`-Block in Compose. ## Lokal bauen Ein erster Build jedes Images dauert etwa 15 Minuten auf einem aktuellen Laptop; nachfolgende Builds treffen den Layer-Cache von Docker und sind in unter einer Minute fertig für das Image, das du geändert hast. ```bash # Bau jedes Image in compose.yml docker compose build # Bau ein Image docker compose build platform ``` Setze `PULL_POLICY=build` in deiner Umgebung (oder in `.env`), um Compose zu zwingen zu bauen, statt das veröffentlichte Image zu ziehen. Die ausgelieferte `compose.yml` defaultet auf `build`, also baut ein lokales Clone ohne Overrides bereits; Produktions-Compose-Dateien, die `tale deploy` generiert, defaulten auf `always` und ziehen aus der Registry. ## Die Anpassungs-Nähte Die unterstützten Erweiterungs-Punkte für Forks sind auf der Dockerfile-Ebene. Der Entrypoint des Images und die Konfigurationsdateien darin sind stabil — patche sie, bau das Image, und der Rest des Systems muss es nicht wissen. - **Caddyfile** — `services/proxy/Caddyfile` steuert Routing und TLS-Terminierung. Custom Header, Custom Subdomains und Custom Rate-Limits landen hier. - **Plattform-Plop-Templates** — `services/platform/Dockerfile` läuft einen Build-Schritt, der die Messages, das Schema und die statischen Assets einbäckt. Ein Fork, der Custom-UI-Strings oder zusätzliche Routes ausliefert, baut das Plattform-Image. - **Sandbox-Runtime-Image** — `services/sandbox-runtime/Dockerfile` ist die Ausführungsumgebung für **Code-ausführen**, Web-Render und Dokumentgenerierung; es trägt bereits Chromium und Playwright. Ein Fork, der ein zusätzliches System-Paket oder einen anderen Browser-Build braucht, patcht hier. - **Sandbox-Egress-Proxy** — `services/sandbox-egress/tinyproxy.conf.template` ist die Proxy-Konfiguration, die der Entrypoint beim Start rendert: standardmäßig offenes Egress, oder ein Default-Deny-Hostname-Filter, wenn `SANDBOX_EGRESS_ALLOWLIST` gesetzt ist. Ein Fork, der anderes Proxy-Verhalten braucht, patcht hier. Was keine unterstützte Naht ist: der Anwendungscode des Convex-Backends, inklusive der Dokument-Extraktion und der RAG- und Crawler-Logik, die jetzt im Prozess leben (`services/platform/convex/`), und der Runtime-Code des Plattform-Containers (`services/platform/app/`). Diese Dateien sind Anwendungscode, keine Konfiguration — einen Dokumentformat-Extraktor hinzuzufügen oder das Retrieval-Verhalten zu ändern ist ein echter Fork und trägt die Upgrade-Steuer. ## Taggen und in eigene Registry pushen Für Air-gapped- oder vendored Distributionen ist der Pfad „bauen, taggen, in deine Registry pushen, die `image:`-Zeilen in Compose ändern". ```bash # Bauen, taggen, pushen export REGISTRY=registry.internal.example.com/tale docker compose build docker tag ghcr.io/tale-project/tale/tale-platform:latest \ $REGISTRY/tale-platform:vendored-1.0 docker push $REGISTRY/tale-platform:vendored-1.0 ``` Der Deploy des CLI generiert eine Compose-Datei mit dem Registry-Pfad; entweder patche die generierte Datei nach der Generierung, oder überspring das CLI und läufe `docker compose` direkt gegen eine Compose-Datei, die du selbst pflegst. ## Mit Upstream synchron bleiben Der günstige Pfad ist ein Fork auf GitHub, der periodisch von `tale-project/tale@main` mergt. Konflikte landen in den Dateien, die du gepatched hast; der Rest geht sauber durch. Die zwei Anti-Patterns: - **Anwendungscode patchen, statt ihn zurückzubeitragen.** Ist die Änderung breit nützlich, upstream einen PR — jede Release-Steuer geht runter. - **Auf ein altes Base-Image pinnen.** Die Caddy-, Bun- und Postgres-Basen nehmen Sicherheits-Patches beim Rebuild auf; die Basis für „Stabilität" zu pinnen heisst Ärger borgen. ## Wo das hingehört Diese Seite ist die contributor-seitige Naht der Operator-Story. Die Architektur-Übersicht lebt in [Container-Architektur](/de/self-hosted/operate/container-architecture); der Upgrade-Workflow, der die veröffentlichten Images läuft, ist in [Upgrades](/de/self-hosted/operate/upgrades). Ist dein Fork nicht-trivial, ist das Gespräch, das es wert ist anzufangen, bevor du Code schreibst, das auf dem Discord oder den GitHub Discussions des Projekts — viele Forks enden als Features, die darauf warten, Upstream zu landen. # Container-Architektur Source: https://tale.dev/docs/de/self-hosted/operate/container-architecture Eine Tale-Instanz besteht aus acht Containern, verdrahtet durch docker compose. Die Architektur-Seite hat behandelt, wofür jeder Container da ist; diese Seite ist die Operator-Version — welcher Container welchen Job besitzt, wie eine Chat-Nachricht durch sie fliesst und wie der Fehlermodus aussieht, wenn einer von ihnen stirbt. Lies das, wenn du Bereitschaft hast. Komm zurück, wenn du entscheidest, welchen Container du während eines Upgrades zuerst rollst. ## Die acht Container, mit ihren Jobs | Container | Job | Ausfälle betreffen | | -------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `tale-proxy` | TLS-Terminierung + Edge-Routing | Jeden Ingress — kein Client erreicht die UI | | `tale-platform` | UI-Server, statische Asset-Auslieferung | Browser sieht 502; die API ist erreichbar | | `tale-convex` | Backend Actions/Queries/Mutations + WebSocket, plus In-Process-RAG, Crawling und Dokumentgen | UI lädt, aber ohne Daten; laufende Chats stocken; Ingestion stockt | | `tale-db` | Operatives Postgres für Convex | Convex fällt in Read-only; Writes blockieren | | `tale-knowledge-db` | Postgres des Wissens-Korpus (Dokument-Chunks, Embeddings, gecrawlte Seiten) | Wissens-Suche liefert leer; Ingestion scheitert | | `tale-sandbox-llm-gateway` | LLM-Gateway für In-Sandbox-Coding-Agents | Sandboxierte Agents erreichen kein Modell; Chat ist unbetroffen | | `tale-sandbox-egress` | Netzwerk-Egress für sandboxierten Code | **Code-ausführen**-Tool scheitert mit „Egress denied"; Web-Render scheitert | | `tale-sandbox` | Sandbox-Laufzeit + Headless-Browser für Web-Render und Dokumentgenerierung | **Code-ausführen**, Web-Crawl-Render und Dokumentgenerierung scheitern alle | Ein Container ist dem öffentlichen Netz exponiert (`tale-proxy` für HTTPS, optional `tale-sandbox-egress` ausgehend für die Sandbox); der Rest nur intern. Der Opt-in-Sidecar `tale-controller` (das `controller`-Profil) ist standardmäßig aus; aktiviert startet er `tale-convex` auf eine signierte Anfrage neu, damit eine Datenresidenz-Änderung greifen kann, ohne der Plattform Docker-Zugriff zu geben. ## Der Request-Pfad Eine Chat-Nachricht macht einen Durchlauf durch die Container: 1. Browser → `tale-proxy` (TLS terminiert). 2. `tale-proxy` → `tale-platform` für HTML/JS, → `tale-convex` für API + WebSocket. 3. `tale-convex` liest die Provider-Config der Organisation, wählt das Modell, öffnet einen Stream zum Upstream-Provider. 4. Holt der Agent Wissen: `tale-convex` fährt die RAG-Suche im Prozess und fragt `tale-knowledge-db` direkt ab — kein separater Retrieval-Dienst im Pfad. 5. Führt der Agent Code aus: `tale-convex` → `tale-sandbox` → `tale-sandbox-egress` für ausgehende Netzwerk-Aufrufe. 6. Der Provider-Stream gibt Tokens durch `tale-convex` zurück an den Browser über den WebSocket. Der heisse Pfad ist kurz. Fühlt sich die Chat-Latenz falsch an, ist der Container, der schuld ist, fast immer der Upstream-Provider, nicht Tale; die Metric-Endpoints auf `tale-convex` (das jetzt auch die RAG- und Crawl-Timings trägt) zeigen die Zeit in jedem Sprung. ## Die Sandbox-Ebene Sandboxierte Code-Ausführung läuft in `tale-sandbox`, mit `tale-sandbox-egress` als der einzigen Netzwerk-Naht. Die Zwei-Container-Trennung ist Absicht: `tale-sandbox` selbst hat kein ausgehendes Netz; jeder Request, den der sandboxierte Code macht, geht durch `tale-sandbox-egress`, der Cloud-Metadaten und private Adressbereiche auf IP-Ebene blockiert und — wenn der Operator `SANDBOX_EGRESS_ALLOWLIST` setzt — zusätzlich eine Default-Deny-Hostname-Allowlist durchsetzt. Ist der Egress-Container down, scheitert sandboxierter Code, der das Netz braucht, geschlossen mit „Egress denied" — nicht stiller Timeout. Die Sandbox-Laufzeit trägt Chromium und Playwright, also nutzt das Convex-Backend sie für die Headless-Arbeit, die es im Prozess nicht erledigen kann, erneut: das Rendern einer JavaScript-Seite während eines Web-Crawls und das Verwandeln von generiertem HTML in ein PDF oder Bild. Diese Jobs laufen als ephemere Sandbox-Ausführungen statt als User-Code, reiten aber dieselbe Egress- und Isolations-Naht. Die Sandbox ist der einzige Container, der eher-nicht-vertrauenswürdigen Code läuft (User-gelieferte Fähigkeits-Skripte, Agent-**Code-ausführen**-Aufrufe); der Rest des Stacks läuft den eigenen Code der Plattform. ## Fehler-Modi — wie der Ausfall jedes Containers aussieht **`tale-proxy` down.** TLS-Handshake scheitert; jeder Client sieht einen Verbindungsfehler. Im Host sind die Plattform- und Convex-Container weiter up — starte Proxy zuerst neu. **`tale-platform` down.** Browser bekommt 502 vom Proxy; die API arbeitet weiter. Bestehende Browser-Tabs mit gecachten Assets sprechen weiter mit Convex über den WebSocket und merken es vielleicht erst beim Reload. **`tale-convex` down.** Browser lädt die UI-Shell, aber nichts wird befüllt. WebSocket-Reconnect schleift. Convex neu zu starten ist sicher — Sessions sind serverseitig; Clients reabonnieren beim Reconnect. **`tale-db` down.** Convex tritt in seinen degradierten Modus: Reads aus dem Cache, Writes werden gepuffert. Lange Ausfälle zeigen sich irgendwann als „Speichern fehlgeschlagen"-Toasts. **`tale-knowledge-db` down.** Dokument-Ingestion scheitert und die Wissens-Suche liefert leer — Agents, die Wissen abrufen, bekommen eine leere Ergebnismenge und eine Warnung im Ausführungs-Log. Der Rest der App arbeitet weiter; Chats ohne Wissen sind unbetroffen. Den Container neu zu starten räumt das, und laufende Uploads versuchen es beim nächsten Durchlauf erneut. **`tale-sandbox` / `tale-sandbox-egress` down.** **Code-ausführen**-Tool-Aufrufe geben einen Fehler zurück und Fähigkeits-Skripte scheitern. Weil das Convex-Backend Webseiten rendert und Dokumente über die Sandbox-Laufzeit generiert, scheitern auch ein Web-Crawl, der JavaScript-Rendering braucht, und die Dokumentgenerierung geschlossen, solange die Sandbox down ist. Agents, die keines davon nutzen, arbeiten weiter. **`tale-sandbox-llm-gateway` down.** In-Sandbox-Coding-Agents verlieren ihren Pfad zu einem Modell-Provider. Regulärer Chat — der Provider direkt aus Convex aufruft, nicht über das LLM-Gateway — ist unbetroffen. ## Wo das hingehört Diese Seite ist die Karte des Operators; die [Architektur-Übersicht](/de/self-hosted/overview) ist die Einführung ins selbe Bild, die [Troubleshooting-Seite](/de/self-hosted/operate/observability/troubleshooting) ist der symptomorientierte Index, wenn etwas schiefgegangen ist. Wenn du Alert-Schwellen setzt, benennt [Operations](/de/self-hosted/operate/observability/operations) die Signale, die sich zu verdrahten lohnen. # Wie du Release-Notes liest Source: https://tale.dev/docs/de/self-hosted/operate/release-notes/format Tale liefert ein Release pro Minor-Version und Patches als Bugfix-Tags dazwischen aus. Die Release-Notes für jeden Tag folgen derselben Form, damit du eine in einer Minute scannen kannst und weißt, ob das Upgrade ein Fünf-Minuten-Bump oder ein Wartungsfenster ist. Diese Seite deckt das Format ab: das semver-Versprechen, was jeder Abschnitt garantiert, und wo du tiefer liest, wenn eine Zeile auf eine Migration zeigt. Die Notes selbst leben auf der GitHub-Release-Seite zu jedem Tag. Das CLI bringt sie ebenfalls hoch — `tale update --notes` druckt die Notes für die Version, die es gerade installieren will. ## Das semver-Versprechen Tale-Versionen sind semver, und die Versionsnummer ist die wichtigste Tatsache über ein Upgrade. - **Patch (`0.9.0 → 0.9.1`)** — nur Bugfixes. Keine Schema-Migrationen, keine Config-Änderungen, keine Verhaltens-Änderungen außer dem Fix selbst. Sicher zu upgraden, ohne weiter als bis zum Security-Abschnitt zu lesen. - **Minor (`0.9.x → 0.10.x`)** — neue Features, möglicherweise forward-only Migrationen. Rückwärtskompatibel standardmäßig; Deprecations werden ein Minor im Voraus angekündigt. - **Major (`0.x → 1.x`)** — breaking Changes sind erlaubt. Trägt immer einen Link auf die Migrations-Notes oben am Release; lies sie End-to-End, bevor du anfängst. Die Versionszeile oben auf jeder Release-Seite nennt die Art des Bumps in Klartext, damit du die Rechnerei nicht selbst machen musst. ## Die Abschnitte, die jedes Release hat Jede Release-Seite ist dieselbe geordnete Abschnitts-Liste. Leere Abschnitte werden weggelassen, nicht leer gelassen — siehst du einen Abschnitt nicht, gibt es dort nichts zu melden. - **Highlights** — ein oder zwei Absätze dazu, wofür das Release da ist. Lies das zuerst. - **Breaking Changes** — jede Änderung, die verlangt, dass der Operator vor oder nach dem Upgrade etwas tut. Jede Zeile nennt das Symptom, das du treffen würdest, wenn du sie überspringst, und die Aktion, die das vermeidet. - **Deprecations** — Features, die in diesem Release noch laufen, aber zur Entfernung markiert sind. Jede Zeile nennt die Removal-Version, damit du den Cutover planen kannst. - **Security** — Einträge im CVE-Format für Fixes, die eine Schwachstelle schließen. Der vollständige Feed lebt unter [Security-Advisories](/de/self-hosted/operate/security/advisories); die Release-Notes tragen die Ein-Zeilen-Zusammenfassung plus den Link auf das Advisory. - **Features und Fixes** — die lange Liste. Gruppiert nach Bereich (Platform, CLI, Docs); jede Zeile liest sich als ein Satz. - **Migrations-Notes** _(Major-Versionen und manche Minors)_ — der verlinkte Walk durch Schema-Migrationen, Config-Datei-Änderungen oder operatorseitige Umbenennungen. Bei Majors immer lesen. ## Wie du ein Release scannst Lies die Versionszeile, die Highlights und den Breaking-Changes-Abschnitt. Ist Breaking Changes leer und nennt der Security-Abschnitt keinen Fix, der dein Install berührt, ist das Upgrade die `tale update` + `tale deploy`-Sequenz aus [Upgrades](/de/self-hosted/operate/upgrades). Hat einer der beiden Abschnitte Zeilen, gehst du sie durch, bevor du `tale deploy` läufst. ```text 0.12.0 (minor) — 14.05.2026 Highlights Streaming-Tool-Calls streamen jetzt in den Chat, sobald sie emittieren. Breaking Changes (keine) Deprecations AGENTS_LEGACY_PROMPT env var — entfernt in 0.14. Security CVE-2026-XXXX — gepatchter Bypass in der Run-Code-Sandbox. Siehe: Advisory TAL-2026-007. ``` Die Form oben ist das, was `tale update --notes` druckt. Die Web-Version desselben Releases fügt auf jeder Advisory- und Migrations-Zeile Links hinzu. ## Wo das hingehört Das Release-Notes-Format ist der Vertrag zwischen Projekt und Operator — dieselbe Form bei jedem Release, damit die Upgrade-Entscheidung ein Scan ist, kein tiefes Lesen. Die natürlichen nächsten Schritte sind [Upgrades](/de/self-hosted/operate/upgrades) für die Deploy-Mechanik und [Security-Advisories](/de/self-hosted/operate/security/advisories) für den langen Schwachstellen-Feed, in den der Security-Abschnitt verlinkt. # tale-daemon Source: https://tale.dev/docs/de/self-hosted/operate/tale-daemon `tale-daemon` führt Tale-Board-Aufgaben auf einer Maschine aus, die du kontrollierst — mit den Coding-Agent-CLIs, die du bereits hast: **Claude Code** (`claude`) und **Codex** (`codex`). Binde einen Agenten in seiner Konfiguration an eine Runtime, und seine zugewiesenen Aufgaben werden an den Daemon geschickt statt an Tales interne Modell-Schleife; das Ergebnis landet als Kommentar (mit Diff-Statistik) auf der Aufgabe, die wie jede andere Agenten-Arbeit bei _In Review_ parkt. Für chatgesteuerte Läufe derselben CLIs in einer verwalteten Sandbox siehe [Externe Agenten](/de/platform/agents/external-agent). ## Setup ```sh tale daemon setup # Basis-URL, API-Schlüssel, Workspace, Berechtigungs-Obergrenze tale daemon start # Registrierung + Claim-Schleife (Strg-C lässt den Lauf ausklingen) tale daemon status # Konfiguration, erkannte CLIs, Server-Erreichbarkeit ``` `setup` erzeugt eine stabile Daemon-Identität und speichert die Konfiguration unter `~/.tale-daemon/config.json` (Modus 600). Nutze einen normalen Tale-API-Schlüssel (**Einstellungen → API → REST**); setze `TALE_DAEMON_API_KEY`, um den Schlüssel aus der Datei herauszuhalten. Verbundene Daemons erscheinen unter **Einstellungen → API → Runtimes** mit Live-Status. Am schnellsten geht es über den Button **Schlüssel erzeugen & Befehl kopieren** unter **Einstellungen → API → Runtimes**: Er erzeugt einen neuen API-Schlüssel und kopiert einen fertigen Befehl, in dem die URL dieses Workspaces und der Schlüssel bereits eingetragen sind. Jede Antwort, nach der `setup` fragt, lässt sich auch als Flag übergeben, sodass der Befehl unbeaufsichtigt läuft: ```sh tale daemon setup --yes --url https://your-org.tale.dev --key <api-key> tale daemon start ``` Der Schlüssel steht in der Befehlszeile — behandle den Ausschnitt als Geheimnis und widerrufe den Schlüssel unter **Einstellungen → API → REST**, falls er nach außen gelangt. ## Datenschutz & Berechtigungen - Lokale Workspace-**Pfade verlassen die Maschine nie** — nur die von dir gewählten Workspace-Schlüssel werden dem Server gemeldet. - Die effektive Berechtigung eines Laufs ist **min(Server-Konfiguration, Daemon-Obergrenze)**. `full_auto` (Berechtigungen überspringen / voller Sandbox-Zugriff) erfordert daher Opt-in auf _beiden_ Seiten. Standard ist `safe`. ## Wie Läufe ausgeführt werden - **Taktung**: der Daemon fragt Arbeit mit server-gesteuertem Backoff ab (3 s nach Arbeit, 15 s im Leerlauf, gedeckelt bei 60 s nach zehn Leerlauf-Minuten — ein untätiger Daemon kostet etwa eine Anfrage pro Minute). Ein 15-s-Heartbeat während eines Laufs erneuert die Server-Lease und nimmt Abbrüche entgegen (SIGTERM). - **Isolation**: jeder Lauf läuft in einem eigenen Git-Worktree auf einem `tale/run-…`-Branch. Es wird nichts gepusht; die Diff-Statistik reist mit dem Bericht. - **Sessions**: Revisions-Läufe (Review-Feedback) setzen die vorherige CLI-Session fort, wo der Adapter es unterstützt. ## Fehlerbehandlung | Situation | Verhalten | | ----------------------------------------------- | --------------------------------------------------------------------------------------------- | | Kein Daemon übernimmt den Lauf binnen 2 Minuten | Lauf schlägt fehl (`runtime_offline`), Aufgabe rollt mit Kommentar nach _Zu erledigen_ zurück | | Daemon stirbt mitten im Lauf (Lease verloren) | Ein Retry aus sauberem Worktree, dann Fehlschlag | | Lauf überschreitet 30 Minuten | Harter Timeout, Behandlung wie oben | | CLI endet mit Fehlercode | Ein Retry, dann Fehlschlag mit Fehler-Auszug | Alle externen Läufe teilen den internen Laufdatensatz — Budgets, Parallelitäts-Limits und Metriken gelten identisch. # Backups und Restore Source: https://tale.dev/docs/de/self-hosted/operate/backups-and-restore Tales Backup-Einheit ist der Volume-Snapshot: ein pausiertes, checksummengesichertes Tar jedes Daten-Volumes der Instanz, geschrieben in ein dediziertes `backups`-Volume, das neben den Daten lebt, die es schützt. Das CLI nimmt automatisch einen vor jedem Deploy-Schritt, der Daten migrieren kann, und `tale backup` nimmt einen auf Zuruf. Recovery ist `tale restore <snapshot-id>` plus ein Redeploy der passenden Version — dieses Paar ist die Antwort auf ein gescheitertes Upgrade und der Grund, warum `tale rollback` sich alles jenseits eines Patch-Schritts verweigern kann. Der Architektur-Kontext lebt in [Container-Architektur](/de/self-hosted/operate/container-architecture); diese Seite deckt ab, was ein Snapshot enthält, wann einer genommen wird, wie die Kopie vom Host runterkommt und den Restore-Walk. ## Was ein Snapshot enthält | Volume | Enthält | | ---------------------------- | ---------------------------------------------------- | | `db-data` | Postgres — Agents, Runs, das Audit-Log | | `convex-data` | Org-Config, Anbieter-Secrets, hochgeladenes Branding | | `rag-data` | Der Vektor-Index aus deinen Dokumenten | | `crawler-data` | Gecrawltes Website-Wissen | | `caddy-data`, `caddy-config` | TLS-Zertifikate und Proxy-State | Jeder Snapshot ist ein Verzeichnis mit einem Namen wie `20260611-142530-deploy` im `backups`-Volume des Projekts: ein `.tar.gz` pro Volume, je ein `.sha256`-Sidecar und ein zuletzt geschriebenes `manifest.json`. Ein Verzeichnis ohne Manifest ist ein unvollständiger Snapshot — er taucht nie in Listings auf und lässt sich nie wiederherstellen. Zwei Dinge leben außerhalb der Volumes und brauchen separate Erfassung: der Projekt-Workspace (das Verzeichnis mit `tale.json`) und `.env`. ## Wann Snapshots genommen werden `tale deploy` snapshotet vor seinem ersten mutierenden Schritt, wann immer der Deploy Daten ändern kann: Die Zielversion weicht von der laufenden ab oder ein Host-Config-Push (`--override` / `--override-all`) ist angefordert. Während jedes Volume getart wird, sind die Container, die es nutzen, für ein paar Sekunden pausiert, damit das Archiv crash-konsistent ist — eine Live-Kopie eines laufenden Postgres-Verzeichnisses ist nicht wiederherstellbar. Ein gescheiterter Snapshot bricht den Deploy ab. `--skip-backup` übersteuert das auf `tale deploy` — dann sind deine eigenen externen Backups der einzige Recovery-Pfad, und genau deshalb loggt das Flag eine laute Warnung. ```bash # Jetzt sofort einen Snapshot nehmen tale backup ``` ## Retention Die Rotation behält die neuesten fünf Snapshots und alles aus den letzten 14 Tagen — je nachdem, was großzügiger ist. Ein Snapshot wird nur gelöscht, wenn er sowohl jenseits des Anzahl-Fensters als auch älter als das Alters-Fenster ist; eine ruhige Instanz behält ihre letzten Snapshots also unbegrenzt. Übersteuere die Fenster mit `BACKUP_KEEP_COUNT` und `BACKUP_KEEP_DAYS` in `.env`. ## Off-Host-Kopie Die Snapshots leben auf demselben Host wie die Daten, die sie schützen — eine tote Platte nimmt beides mit. Richte dein bestehendes Backup-Tooling (Restic, Borg, Velero, Cloud-Provider-Snapshots) auf das `backups`-Volume und erfasse den Projekt-Workspace und `.env` im selben Job. Tale bringt keinen Upload-Schritt mit — die Off-Host-Kopie unter deinem bestehenden Backup-Vertrag zu halten ist Absicht. ```bash # crontab auf dem Host — stündliche Restic-Kopie des backups-Volumes nach S3 0 * * * * restic -r s3:s3.amazonaws.com/bucket/tale backup \ /var/lib/docker/volumes/<project-id>_backups/_data ``` Den Host-Pfad des Volumes findest du mit `docker volume inspect <project-id>_backups`; die Projekt-ID steht in `tale.json`. ## Einen Snapshot wiederherstellen `tale restore` ohne Argumente listet, was verfügbar ist; mit einer ID verifiziert es die Checksummen, leert die Daten-Volumes und entpackt den Snapshot. Es verweigert, solange irgendein Projekt-Container läuft — `--stop` stoppt sie — und fragt nach Bestätigung, bevor es irgendetwas anfasst. ```bash # Sehen, was verfügbar ist tale restore # Stack stoppen und wiederherstellen tale restore 20260611-142530-deploy --stop # Den Stack auf der Version zurückbringen, die zu den Daten passt tale update --version 0.9.6 tale deploy --stop ``` Das Redeploy der passenden Version ist Teil des Restores, kein optionales Extra: Der Snapshot hat die Daten exakt so erfasst, wie diese Plattform-Version sie hinterlassen hat, und ein neueres Binary würde sofort wieder seine Migrationen darauf laufen lassen. Die Restore-Ausgabe druckt die exakte Version aus dem Manifest des Snapshots. ## Restore-Drill Lauf den Drill vierteljährlich auf einem Nicht-Produktions-Host. Der Drill ist nicht „existiert ein Snapshot" — er ist „kann ein frischer Host aus der Off-Host-Kopie des `backups`-Volumes, dem Projekt-Workspace und `.env` in unter einer Stunde wiederaufgebaut werden". Die Fehler-Modi, die der Drill fängt: ein Off-Host-Job, der den Workspace nie erfasst hat, und eine veraltete `.env`, die nicht mehr zu den Anforderungen des aktuellen Binarys passt. ## Wo das hingehört Snapshots sind der billige Teil; der Restore-Drill ist das, was beweist, dass sie funktionieren, und die Redeploy-der-passenden-Version-Regel ist das eine, was du dir merken solltest — Recovery ist nie „das Binary zurückrollen", sondern „die Daten wiederherstellen und die Version deployen, zu der sie gehören". Der Upgrade-Flow, den diese Snapshots schützen, lebt in [Upgrades](/de/self-hosted/operate/upgrades); die Hardening-Checkliste, die Backups als Zeile nennt, ist in [Hardening](/de/self-hosted/operate/security/hardening). # Security-Advisories Source: https://tale.dev/docs/de/self-hosted/operate/security/advisories Tale veröffentlicht ein Security-Advisory für jede Schwachstelle, die durch ein gepatchtes Release geschlossen wird. Der Feed lebt unter GitHub Security Advisories im Repository `tale-project/tale` und spiegelt auf einen RSS-Endpunkt, den Operator in ihr Alerting hängen können. Diese Seite deckt das Format ab, dem jedes Advisory folgt, die Severity-Skala, die Tale verwendet, die Disclosure-Timeline, der die Maintainer sich verpflichten, und die drei Subscription-Pfade. Die Advisories sind die Langform-Aufzeichnung. Die Ein-Zeilen-Zusammenfassung plus Link erscheint im **Security**-Abschnitt jeder [Release-Note](/de/self-hosted/operate/release-notes/format). ## Das Advisory-Format Jedes Advisory ist ein GitHub Security Advisory mit einem stabilen Identifier der Form `TAL-YYYY-NNN` (Tales interne ID) plus dem Upstream-`CVE-YYYY-NNNNN`, wenn eine zugewiesen wurde. Der Body ist dieselbe geordnete Abschnittsmenge, damit ein Operator die tragenden Fakten scannen kann, ohne die Prosa zu lesen. - **Summary** — ein Satz dazu, was ein Angreifer tun könnte und was der Fix ändert. - **Affected versions** — die Versions-Range, die die Schwachstelle enthält, in semver-Form (`>=0.8.0, <0.12.3`). - **Patched versions** — das erste Release, das den Fix enthält. Das Upgraden auf oder über diese Version schließt die Schwachstelle. - **Severity** — eine der vier Stufen unten, plus der CVSS-3.1-Vektor für Operator, die gegen ihr eigenes Threat-Model scoren. - **Workarounds** — was zu setzen, zu deaktivieren oder zu blockieren ist, um die Schwachstelle zu mitigieren, wenn ein sofortiges Upgrade nicht möglich ist. Leer, wenn kein Workaround existiert. - **Credits** — der Melder, wenn er namentlich genannt werden möchte. Die Patched-Versions-Zeile ist die, auf der die meisten Operator zuerst landen; das Upgrade selbst ist die Zwei-Kommando-Sequenz aus [Upgrades](/de/self-hosted/operate/upgrades). ## Die Severity-Skala Tale nutzt vier Stufen. Die Stufe wird aus dem CVSS-Score und der Erreichbarkeit der verwundbaren Oberfläche auf einem Standard-Install gesetzt. | Stufe | CVSS | Was es bedeutet | | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Critical | 9.0+ | Pre-authentifizierte Remote-Code-Execution oder unauthentifizierte Daten-Exfiltration. Patche innerhalb 24 Stunden. | | High | 7.0–8.9 | Authentifizierte Eskalation, Sandbox-Ausbruch oder Cross-Tenant-Daten-Leak. Patche innerhalb einer Woche. | | Moderate | 4.0–6.9 | Informations-Disclosure, Denial of Service oder Eskalation, die seltene Vorbedingungen verlangt. Patche im nächsten Wartungsfenster. | | Low | 0.1–3.9 | Defense-in-Depth-Fixes und Härtung ohne bekannten Exploit-Pfad. Patche, wenn es passt. | Der CVSS-Vektor lässt dich gegen dein eigenes Deployment neu scoren — ein Advisory, das gegen ein öffentliches Install High ist, kann gegen ein air-gapped Install Low sein. ## Die Disclosure-Timeline Die Maintainer verpflichten sich auf die folgende Timeline ab dem Moment, in dem ein Report bei `security@tale.dev` landet: - **Innerhalb 72 Stunden** — Bestätigung, ein Triage-Call und ein zugewiesener TAL-Identifier. - **Innerhalb 14 Tagen** — ein Fix oder ein Workaround, privat an den Melder veröffentlicht, und die gepatchte Version geplant. - **Bei Fix-Release** — das Advisory wird auf GitHub veröffentlicht, die CVE-Zuweisung wird angefordert, und der Security-Abschnitt der Release-Notes trägt die Zusammenfassung. - **30 Tage nach Release** — das technische Detail im Advisory erweitert sich um den Reproducer (wenn das Reproduzieren in der Öffentlichkeit ungepatchte Installs nicht mehr gefährdet). Melder können eine Verzögerung anfordern, wenn sie für die Offenlegung mehr Zeit brauchen; die Maintainer akzeptieren bis zu 90 Tage, bevor sie die Zusammenfassung trotzdem veröffentlichen. Auf der Engineering-Seite laufen Dependency-Fixes auf einem Fast Track, damit das gepatchte Release schnell erscheint: Renovate öffnet innerhalb von 24 Stunden nach einem Upstream-Advisory einen Security-Update-PR — am sonst üblichen Release-Age-Delay für Routine-Updates vorbei — und CI blockt jeden Merge, der ein bekanntes High- oder Critical-Advisory einführt. Ein offengelegter Dependency-CVE wird damit in Tagen zu einem gepatchten Tale-Release, nicht erst beim nächsten Routine-Zyklus. ## Anmelden Drei Pfade zum selben Feed: ```text GitHub-Watch — github.com/tale-project/tale → Watch → Custom → Security alerts RSS — https://github.com/tale-project/tale/security/advisories.atom E-Mail-Digest — security-announce@tale.dev (eine Mail pro Advisory, kein Verkehr dazwischen) ``` Der RSS-Feed ist das, was die meisten Operator in Slack oder PagerDuty einhängen; der E-Mail-Digest ist für Ein-Personen-Teams, die keine Alerting-Pipeline betreiben. ## Wo das hingehört Der Advisory-Feed ist einer der zwei Verträge, die Tale sicher selbst hostbar machen — Release-Notes nennen, was sich ändert, Advisories nennen, was falsch war. Die natürlichen nächsten Lesungen sind [Wie du Release-Notes liest](/de/self-hosted/operate/release-notes/format) für das passende Change-Log-Format und [Hardening](/de/self-hosted/operate/security/hardening) für die Checkliste, die Exposition begrenzt, bevor ein Advisory überhaupt feuert. # Kryptografie Source: https://tale.dev/docs/de/self-hosted/operate/security/cryptography Diese Seite ist die Inventur jedes kryptografischen Primitivs, auf das sich Tale stützt: was Secrets auf der Festplatte schützt, was den Verkehr auf der Leitung schützt, wie Passwörter gehasht werden und wie das Audit-Log beweist, dass es nicht manipuliert wurde. Sie ist für Betreiber und Compliance-Prüfer geschrieben, die "welche Algorithmen, welche Schlüssellängen, wo liegen die Schlüssel" gegen einen Standard wie BSI TR-02102-1 beantworten müssen — Tale nutzt bereits konforme Primitive, und auf dieser Seite sind sie festgehalten. Die Angaben hier sind gegen den Quellcode verifiziert; wo ein Primitiv konfigurierbar ist, wird die Umgebungsvariable benannt, die es steuert, damit du dein eigenes Deployment prüfen kannst. Das ist kein Ersatz dafür, die Host-Festplatte zu verschlüsseln — siehe [Härtung](/de/self-hosted/operate/security/hardening) für die Schicht unter der Anwendung. ## Ruhende Daten Tale verschlüsselt zwei Klassen von Secrets im Ruhezustand, mit zwei verschiedenen Mechanismen. **Provider-API-Schlüssel** liegen in `providers/*.secrets.json` und werden mit [SOPS](/de/self-hosted/configuration/secrets-with-sops) unter Nutzung eines **age**-Schlüssels verschlüsselt. SOPS verschlüsselt jeden Wert mit **AES-256-GCM** und wrappt den Datenschlüssel an den age-Empfänger, dessen Schlüsselaustausch **X25519** ist. Ein verschlüsselter Wert liest sich auf der Festplatte als `ENC[AES256_GCM,data:…,iv:…,tag:…]`; die Entschlüsselung passiert in-process und der private age-Schlüssel verlässt den Speicher des platform-Containers nie. **Anwendungsverschlüsselte Felder** — OAuth-Integrations-Tokens und ähnliche Credentials in der Datenbank — werden mit **AES-256-GCM** über ein kompaktes JWE (`alg: dir`, `enc: A256GCM`) verschlüsselt. Der 32-Byte-Schlüssel kommt aus `ENCRYPTION_SECRET` (base64) oder `ENCRYPTION_SECRET_HEX` (hex); die Plattform verweigert den Start des Verschlüsselungspfads mit einem Schlüssel, der nicht exakt 32 Byte hat. Der Convex-Datenspeicher und die Postgres-Volumes werden vom Host geschützt: betreibe sie auf einem verschlüsselten Dateisystem (LUKS oder die Volume-Verschlüsselung deines Cloud-Anbieters). Tale speichert Credentials nicht im Klartext — ein Provider-Schlüssel oder OAuth-Token ist entweder SOPS-verschlüsselt auf der Festplatte oder AES-256-GCM-verschlüsselt in der Datenbank, nie im Klartext geschrieben. **Kunden-PII und Anwendungsdaten** — Namen, E-Mail- und Postadressen, Gesprächsinhalte — sind im Ruhezustand durch dieselben Schichten geschützt, die die Datenbank als Ganzes schützen: Convex' Verschlüsselung im Ruhezustand, TLS 1.3 bei der Übertragung und zeilenbasierte Sicherheitsregeln (RLS), die jeden Lesezugriff auf die Organisation des Aufrufers begrenzen. Anwendungsseitige Feldverschlüsselung ist gezielt für Secrets gemacht — Provider-Schlüssel und OAuth-Tokens, die einmal geschrieben und von einem einzigen Code-Pfad gelesen werden. PII ist anders: Sie wird gefiltert, sortiert und über den exakten Wert nachgeschlagen, und die Kundentabelle ist nach Organisation und E-Mail indiziert. Diese Spalten auf Feldebene zu verschlüsseln würde Gleichheitsabfragen und indizierte Suche brechen — sofern nicht mit einem suchbaren Hash-Verfahren kombiniert, das genau die Gleichheit preisgibt, die es verbergen soll — bei zusätzlichen Kosten für die Schlüsselrotation und ohne Schutz, den die verschlüsselte Host-Festplatte unter der Anwendung gegen ein gestohlenes Volume nicht ohnehin bietet. Wenn dein Compliance-Regime zusätzlich Feldverschlüsselung für PII verlangt, ist das eine bewusste Anwendungsänderung statt eines Standards, den Tale mitliefert. ## Daten bei der Übertragung Aller Browser- und API-Verkehr terminiert TLS am Reverse-Proxy (Caddy), der TLS 1.3 (mit TLS 1.2 als Untergrenze) aushandelt und Zertifikate automatisch bezieht. Die Cipher-Suites sind die modernen Defaults des Proxys — AES-256-GCM und ChaCha20-Poly1305 mit ECDHE-Schlüsselaustausch. Konfiguriere Domain und Zertifikatsquelle in [TLS und Domains](/de/self-hosted/configuration/tls-and-domains); der Verkehr zwischen Containern bleibt im internen Docker-Netz des Hosts. ## Passwort-Hashing Lokale-Passwort-Konten werden mit **bcrypt** gehasht (über Better Auth), sodass eine gestohlene Datenbankzeile das Passwort nicht preisgibt und eine Verifikation bewusst ~100 ms kostet — was auch der Grund ist, warum das Timing des Login-Pfads verschleiert wird (siehe [Authentifizierung](/de/self-hosted/configuration/authentication)). Sessions werden mit `BETTER_AUTH_SECRET` (HMAC) signiert; das Rotieren dieses Secrets entwertet jede bestehende Session. ## Integrität des Audit-Logs Das Audit-Log ist über eine **SHA-256-Hash-Kette** manipulationssicher: jeder Eintrag speichert `SHA-256(previousHash + kanonisierter Datensatz)`, sodass das Ändern oder Löschen eines historischen Eintrags die Kette an dieser Stelle und bei jedem folgenden Eintrag bricht. Einträge tragen zusätzlich eine **HMAC-SHA-256**-Signatur. Die Admin-Integritätsprüfung verifiziert beides; siehe [Audit-Logs](/de/platform/admin/governance/audit-logs). ## Zuordnung zu BSI TR-02102-1 Jedes Primitiv unten liegt im empfohlenen Satz von BSI TR-02102-1. Tale liefert keinen veralteten Algorithmus aus (kein MD5, SHA-1, DES oder RSA < 3072 auf einem selbst erzeugten Schlüssel). | Verwendung | Algorithmus | Schlüssel-/Ausgabegröße | Gesteuert durch | | ----------------------- | --------------------------------- | ----------------------- | --------------------------------------------- | | Provider-Secrets (Disk) | AES-256-GCM + age (X25519) | 256-Bit | `SOPS_AGE_KEY` / `SOPS_AGE_KEY_FILE` | | App-Felder (Datenbank) | AES-256-GCM (JWE `dir`/`A256GCM`) | 256-Bit | `ENCRYPTION_SECRET` / `ENCRYPTION_SECRET_HEX` | | Übertragung | TLS 1.3 (AES-256-GCM, ECDHE) | 256-Bit | Reverse-Proxy / `tls-and-domains` | | Passwort-Hashing | bcrypt | Salt pro Hash | Better Auth (eingebaut) | | Session-Signierung | HMAC-SHA-256 | 256-Bit | `BETTER_AUTH_SECRET` | | Audit-Integrität | SHA-256-Kette + HMAC-SHA-256 | 256-Bit | eingebaut | ## Schlüsselspeicherung und -rotation Drei Secrets sind tragend, und jedes hat einen Rotationspfad. Der **private age-Schlüssel** (`SOPS_AGE_KEY`) entschlüsselt Provider-Secrets; rotier ihn, indem du einen neuen Empfänger hinzufügst und neu verschlüsselst, entlang des Wegs in [Secrets mit SOPS](/de/self-hosted/configuration/secrets-with-sops). Der **Feld-Verschlüsselungsschlüssel** (`ENCRYPTION_SECRET`) entschlüsselt Datenbank-Credentials; ihn zu rotieren erfordert das Neu-Verschlüsseln der betroffenen Zeilen, plan es also als Wartungsschritt statt als Hot-Swap. Das **Auth-Secret** (`BETTER_AUTH_SECRET`) signiert Sessions; es zu rotieren loggt alle bei ihrer nächsten Anfrage aus. Alle drei leben nur in der Umgebung des platform-Containers — committe sie nie und leg sie in deinem Secret-Manager der Wahl ab. ## Wo das hingehört Kryptografie in Tale ist geschichtet: SOPS+age und AES-256-GCM schützen Secrets im Ruhezustand, TLS 1.3 schützt sie bei der Übertragung, bcrypt schützt Passwörter, und eine SHA-256-Kette beweist, dass das Audit-Log intakt ist — alles Primitive, die im empfohlenen Satz von BSI TR-02102-1 liegen, mit den steuernden Umgebungsvariablen oben, damit du deine eigene Instanz verifizieren kannst. Die Schicht unter der Anwendung ist der Host selbst: [Härtung](/de/self-hosted/operate/security/hardening) deckt die Egress-Allowlist, die Container-Isolation und die Erwartungen an die Festplattenverschlüsselung ab, die diese Seite voraussetzt, und [Secrets mit SOPS](/de/self-hosted/configuration/secrets-with-sops) ist die operative Anleitung für den age-Schlüssel, von dem diese Algorithmen abhängen. # Audit-Log-Integritätswarnungen Source: https://tale.dev/docs/de/self-hosted/operate/security/audit-log-integrity Tale verifiziert die Audit-Log-Hash-Kette jeder Organisation nach Zeitplan und löst in dem Moment eine Warnung aus, in dem eine Verifizierung fehlschlägt. Diese Seite ist das Runbook für den Operator oder Admin, der diese Warnung erhalten hat: wie du den Befund liest, wie du ein echtes Manipulationssignal von einem gewöhnlichen Aufbewahrungs- oder Konfigurationsartefakt trennst und was du sicherst, bevor du irgendetwas anfasst. Die Warnung ist absichtlich laut, weil ein echter Bruch selten und ernst ist — aber die meisten Brüche, die in der Praxis feuern, haben eine alltägliche Erklärung, also besteht die Arbeit darin, diese methodisch auszuschließen, statt in Panik zu verfallen. ## Was sie auslöst Ein täglicher Cron läuft die append-only Audit-Kette jeder Organisation samt ihrer Aufbewahrungs- und Scrub-Checkpoints ab. Wenn eine Kette nicht verifiziert, tut der Lauf zwei Dinge. Er schreibt eine In-Band-Audit-Zeile der Kategorie `security` — bei jedem fehlschlagenden Lauf, damit der dauerhafte Datensatz immer vollständig ist — und er löst eine Out-of-Band-Benachrichtigung an die Admins der Organisation aus, in der Benachrichtigungsglocke und in deinem Slack-Kanal, wenn einer verbunden ist. Die Out-of-Band-Warnung ist dedupliziert. Du bekommst eine Benachrichtigung, wenn ein Bruch zuerst erkannt wird, und nur dann eine weitere, wenn er sich ändert — eine andere gebrochene Zeile oder ein anderer fehlschlagender Checkpoint — nicht jeden Tag einen frischen Alarm für denselben Bruch. Ein späterer sauberer Lauf räumt die Warnung von selbst ab; ein späterer, anderer Bruch löst eine neue aus. ## Manipulation oder Konfigurationslücke Die Warnung kommt in zwei Formen, und der Titel sagt dir, welche. **Integritätsprüfung des Audit-Logs fehlgeschlagen** ist die kritische: Die Hash-Kette selbst verifiziert nicht, oder die Signatur eines signierten Checkpoints passt nicht zum konfigurierten Schlüssel. Behandle das als mögliches Manipulationssignal, bis du es erklärt hast. **Audit-Log-Signaturen können nicht überprüft werden** ist eine ruhige Warnung, kein Einbruch: Ein Checkpoint ist signiert, aber das Deployment hat keinen `TALE_AUDIT_SIGNING_KEY` konfiguriert, gegen den sich die Signatur prüfen ließe. Nichts wurde gefälscht — Tale kann nur nicht beweisen, dass der Checkpoint echt ist, bis du den Schlüssel wiederherstellst. Das Panel im Produkt spiegelt die Trennung: Eine gesunde Kette zeigt das grüne Badge **Verifiziert**, ein aktiver Vorfall das rote Badge **Integritätswarnung aktiv**, und eine Organisation, die der Cron noch nicht erreicht hat, zeigt **Noch nicht geprüft**. ## Das Integritäts-Panel öffnen Die Admins einer Organisation inspizieren die Kette unter **Einstellungen > Richtlinien > Audit-Logs**. Das Panel **Ketten-Integrität** oben auf der Seite zeigt das Status-Badge, den Zeitpunkt der letzten automatischen Prüfung und einen Knopf **Jetzt prüfen**, der dieselbe Verifizierung auf Abruf erneut fährt. Kommst du aus der Benachrichtigung, führt dich ein Klick auf die Warnung per Deep-Link direkt zur markierten Zeile in der Audit-Tabelle statt an den Anfang des Logs. Fahre **Jetzt prüfen**, um den strukturierten Befund zu sehen. Bei einem Bruch der Hash-Kette zeigt das Panel **Ketten-Integrität verletzt** mit der **Eintrags-ID** der ersten fehlschlagenden Zeile, wann er **Aufgetreten** ist, dem **Erwarteter Hash** und dem **Gespeicherter Hash**, der nicht passte — plus einem Knopf **Diesen Eintrag öffnen**, der die Zeile in der Tabelle aufdeckt. Bei einem Checkpoint-Problem zeigt es **Checkpoint-Prüfung fehlgeschlagen** mit der **Checkpoint-ID** und einem **Grund**. Halte diese Details fest, bevor du irgendetwas änderst: Sie sind der Beweis. ## Die harmlosen Ursachen ausschließen Ein Hash-Bruch ist nur dann ein Manipulationssignal, wenn nichts Legitimes ihn erklärt, und der Verifizierer kennt die drei gewöhnlichen Ereignisse bereits, die fast jede Warnung verursachen — sie zu bestätigen ist dein erster Zug. **Ein Aufbewahrungsschnitt.** Wenn die Aufbewahrung alte Zeilen endgültig löscht, zeigt der überlebende Kettenkopf auf eine Zeile, die nicht mehr existiert. Der Verifizierer verankert die Kette über den Schnitt hinweg neu, über einen signierten Aufbewahrungs-Checkpoint — ein sauberer Schnitt verifiziert also normal. Siehst du stattdessen **Audit-Log-Signaturen können nicht überprüft werden**, ist der Schnitt selbst in Ordnung — dem Deployment fehlt der `TALE_AUDIT_SIGNING_KEY`, der den Checkpoint beglaubigt. Das ist eine Konfigurationslücke, keine Manipulation. **Ein DSGVO-Scrub.** Das Löschen einer betroffenen Person leert ihre Felder an Ort und Stelle, was die Hashes dieser Zeilen ändern würde — deshalb schreibt ein Scrub einen signierten Scrub-Checkpoint über die betroffenen Zeilen, und der Verifizierer vertraut ihnen auf dieser Grundlage. Ein Scrub sollte auf einem Deployment mit Signierschlüssel nie als Bruch auftauchen. **Alte Zeilen aus der Zeit vor der Kette.** Zeilen, die geschrieben wurden, bevor es die Audit-Hash-Verkettung gab, tragen keinen Integritäts-Hash. Der Verifizierer überspringt sie automatisch; sie sind kein Bruch. Ein echtes Manipulationssignal ist ein Hash-Unterschied ohne jede dieser Erklärungen: kein Aufbewahrungsschnitt an dieser Stelle, kein Scrub über der Zeile, und der Signierschlüssel vorhanden und korrekt. ## Auf einen echten Bruch reagieren Übersteht der Befund diese Triage — ein Hash-Unterschied, den du nicht erklären kannst —, behandle ihn als Sicherheitsvorfall und sichere zuerst die Beweise. Audit-Zeilen sind absichtlich append-only; lösche oder bearbeite keine Zeile, auch nicht die markierte, denn das zerstört den Datensatz, von dem eine Untersuchung abhängt. 1. Halte den Befund wörtlich fest — die **Eintrags-ID**, die Zeit unter **Aufgetreten**, **Erwarteter Hash** und **Gespeicherter Hash** (oder die **Checkpoint-ID** und den **Grund**) aus dem Panel. Kopiere sie oder mach einen Screenshot, statt dich allein auf die Warnung zu verlassen. 2. Bestätige, ob der Signierschlüssel auf dem Host konfiguriert ist, damit du einen echten Unterschied von einem nicht verifizierbaren Checkpoint unterscheiden kannst. Das meldet die Anwesenheit, ohne das Geheimnis auszugeben: ```bash grep -q '^TALE_AUDIT_SIGNING_KEY=' .env && echo configured || echo missing ``` 3. Korreliere den Zeitstempel des Bruchs mit jüngerer Aktivität — einem Aufbewahrungslauf, einem Scrub einer betroffenen Person, einem Deploy, einer Datenbank-Wiederherstellung oder direktem Datenbankzugriff. Ein Bruch, der mit einer Wartungsaktion zusammenfällt, hat meist eine gewöhnliche Ursache, die du jetzt benennen kannst. 4. Erklärt ihn nichts, eskaliere über deine Security-Incident-Richtlinie und behandle die Datenbank als potenziell kompromittiert, bis das Gegenteil bewiesen ist. Bewahre je einen Backup-Snapshot von vor und nach dem erkannten Bruch für die Forensik auf. ## Die Warnung abräumen Die Warnung ist vorfallbasiert, kein wiederkehrendes Ereignis. Sobald der Bruch behoben oder erklärt ist — der Schlüssel wiederhergestellt, das Aufbewahrungsartefakt verstanden, eine manipulierte Datenbank aus einem sauberen Backup neu aufgebaut —, verifiziert der nächste tägliche Lauf sauber und räumt die Warnung von selbst ab, und das Badge **Ketten-Integrität** kehrt zu **Verifiziert** zurück. Es gibt keinen Bestätigen- oder Verwerfen-Schritt, den du dir merken müsstest. Taucht später ein anderer Bruch auf, löst die Prüfung dafür eine frische Warnung aus — Stummschalten ist also nie nötig. ## Wo das einzuordnen ist Eine Integritätswarnung ist eine Aufforderung zur Untersuchung, kein Urteil — die tägliche Prüfung läuft laut, damit sich ein seltener echter Bruch nicht zwischen den Logs verstecken kann, und dieses Runbook trennt diesen seltenen Fall von den Aufbewahrungs- und Scrub-Artefakten hinter den meisten Warnungen. Der Mechanismus, den der Verifizierer prüft — die SHA-256-Hash-Kette und die HMAC-signierten Checkpoints — ist in [Kryptografie](/de/self-hosted/operate/security/cryptography) dokumentiert, und die Aufbewahrungsschnitte, die sie legitim neu verankern, stehen in [Aufbewahrung](/de/self-hosted/configuration/retention). Das Panel, die Spalten und der Export, mit denen du eine markierte Zeile liest, leben in der Referenz [Audit-Logs](/de/platform/admin/governance/audit-logs); die Checkliste [Härtung](/de/self-hosted/operate/security/hardening) ist der Ort, an dem dieses Monitoring überhaupt erst eingeschaltet wird. # Hardening Source: https://tale.dev/docs/de/self-hosted/operate/security/hardening Die Defaults, mit denen Tale ausgeliefert wird, sind sicher für Development und vernünftig für eine kleine Produktions-Installation. Von „vernünftig" zu „bereit für die Regulator" zu kommen ist eine Checkliste, kein Konfigurations-Flag — jede Zeile unten zieht eine spezifische Angriffsoberfläche an. Walk die Liste einmal, bevor du die URL für echte Benutzer öffnest, und walk sie nach jedem grösseren Upgrade erneut. Die Referenz-Details für jede Zeile leben anderswo — TLS in [TLS und Domains](/de/self-hosted/configuration/tls-and-domains), Backups in [Backups und Restore](/de/self-hosted/operate/backups-and-restore), Retention in [Retention](/de/self-hosted/configuration/retention). Diese Seite ist der Index, der nennt, was zu härten ist und auf die Seite zeigt, die es walkt. ## Host | Punkt | Warum es zählt | | ------------------------------------ | ------------------------------------------------------------------------- | | Non-Root-Operator-Benutzer | Begrenzt den Blast-Radius, wenn der Plattform-Benutzer kompromittiert ist | | Nur SSH-Schlüssel-Auth | Passwort-Auth ist die offene Tür, nach der Bots scannen | | Unbeaufsichtigte Sicherheits-Updates | Patcht das OS, ohne auf ein Wartungsfenster zu warten | | Host-Firewall (ufw / nftables) | Schliesst alles, was nicht 22, 80, 443 ist | | Platten-Verschlüsselung at-rest | Pflicht, wenn du SOPS im Klartext-Modus betreibst | Der Non-Root-Benutzer ist der, den die meisten Teams überspringen. Die Container von Tale laufen ihre eigenen Non-Root-Prozesse innen, aber der Docker-Daemon selbst läuft als Root — diesen Daemon als Operator-Benutzer zu betreiben (Mitglied der `docker`-Gruppe, nicht als Root) ist das günstigste Anziehen auf dieser Seite. Der vollständige Walk lebt in [Produktions-Linux-Server-Install](/de/self-hosted/install/linux-server). ## Netzwerk Der Proxy ist die einzige eingehende Oberfläche. Blockier alles andere. ```bash sudo ufw default deny incoming sudo ufw default allow outgoing sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable ``` Wenn du trusted-Headers-Auth betreibst, darf der Plattform-Port nicht direkt von irgendwo ausser dem vorgelagerten Proxy erreichbar sein — alles, was ihn mit den richtigen Headern treffen kann, wird zu diesem Benutzer. Ein Docker-Netzwerk oder eine Host-Firewall-Regel funktionieren beide; wähl eins und verifizier es von ausserhalb des Hosts. ## TLS `TLS_MODE=selfsigned` ist für Development. Produktion läuft `letsencrypt` (oder `external`, wenn du Tale mit deinem eigenen TLS-terminierenden Proxy davor stellst). Der Erneuerungs-Cron ist automatisch; der Alert, der feuert, wenn die Erneuerung scheitert, ist das, was dich 90 Tage später rettet. Siehe [TLS und Domains](/de/self-hosted/configuration/tls-and-domains). ## Secrets Jedes Secret in `.env` ist sensibel — das Auth-Signing-Secret, der Verschlüsselungs-Schlüssel, das Datenbank-Passwort, der age-Schlüssel, das Metric-Bearer-Token. Die Mindestmesslatte: - `.env` ist Modus 0600 und gehört dem Operator-Benutzer. - `BETTER_AUTH_SECRET`, `ENCRYPTION_SECRET_HEX`, `INSTANCE_SECRET` sind von den Beispielwerten weg rotiert, die `.env.example` mitbringt. - `DB_PASSWORD` ist vom Default-Platzhalter geändert. - `SOPS_AGE_KEY` oder `SOPS_AGE_KEY_FILE` ist gesetzt — beide unset zu lassen ist unterstützt, aber Hosts mit verschlüsselter Platte und externem Secret-Management vorbehalten. Der vollständige SOPS-Walk und die Rotations-Prozedur leben in [Secrets mit SOPS](/de/self-hosted/configuration/secrets-with-sops). ## Audit-Logs Audit-Logs sind unveränderlich und retentions-gebunden. Compliance-Frameworks erwarten mindestens ein Jahr; die Grenze wird pro Deployment durchgesetzt, also ist die strengste Einstellung der Org das, was tatsächlich läuft. Setz die Untergrenze in deiner Operator-Config so, dass sie zum lockersten Framework passt, das du unterstützt, und stell sicher, dass Backups Audit-Log-Zeilen mit dem Rest der Datenbank erfassen. Die Retention-Referenz lebt in [Retention](/de/self-hosted/configuration/retention). ## Backups Ein Backup, das nicht wiederhergestellt wurde, ist eine Hoffnung, kein Backup. Das Minimum: tägliche Postgres-Dumps, vom `tale-db`-Cron geschrieben, innerhalb der Stunde vom Host weg kopiert, und ein vierteljährlicher Restore-Drill, der eine funktionierende Instanz aus dem Snapshot wieder aufbaut. Die vollständige Prozedur ist in [Backups und Restore](/de/self-hosted/operate/backups-and-restore). ## Sandbox-Isolation Run-Code ist die riskanteste Oberfläche im Produkt — der einzige Ort, an dem benutzergelieferter Input zu ausgeführtem Code wird. `tale-sandbox` läuft ohne privilegierte Caps, sein Netzwerk ist intern, und `tale-sandbox-egress` ist sein einziger ausgehender Pfad. Auf Hostname-Ebene ist dieser Pfad standardmäßig offen: sandboxierter Code erreicht jeden öffentlichen Host über HTTPS, während Cloud-Metadaten-Endpunkte und private Adressbereiche auf IP-Ebene immer blockiert sind — dieser Boden hält in jeder Konfiguration. Der Hardening-Hebel ist `SANDBOX_EGRESS_ALLOWLIST`. Setz die Variable in `.env` auf eine Pipe-getrennte Liste von Hostname-Regexen und erzeuge `tale-sandbox-egress` neu — der Proxy kippt auf Default-Deny, nur passende Hosts sind erreichbar. Ein Lockdown auf reine Registries, der pip, npm, uv und Git über HTTPS am Laufen hält: ```bash SANDBOX_EGRESS_ALLOWLIST=^pypi\.org$|^files\.pythonhosted\.org$|^registry\.npmjs\.org$|^objects\.githubusercontent\.com$|^codeload\.github\.com$|^github\.com$|^api\.github\.com$ ``` Halt die Liste kurz und bevorzuge spezifische Hosts gegenüber Wildcards. Paket-Installationen regelt separat die [Run-Code-Richtlinie](/de/platform/admin/governance/run-code-policy). ## Monitoring `METRICS_BEARER_TOKEN` ist in `.env.example` unset — das ist Absicht, damit eine frische Installation keine Metriken leakt. Setz den Token, scrape aus deinem Prometheus, und die Alert-Schwellen in [Operations](/de/self-hosted/operate/observability/operations) decken die kundenwirksamen Signale ab. Die Hash-Kette des Audit-Logs wird automatisch jede Nacht verifiziert. Jeder Bruch löst einen kritischen Security-Alert an die Org-Admins aus — in der Notification-Glocke und, wenn Slack verbunden ist, in deinem Slack-Channel —, sodass Manipulation auffällt, auch wenn niemand die Logs beobachtet. Dieselbe Verifikation kannst du jederzeit on demand von der Admin-Audit-Log-Seite aus neu walken. ## Wo das hingehört Hardening ist keine Ein-Durchgangs-Aufgabe — die Liste oben ist das, was du vor dem Launch walkst und nach jedem Upgrade oder nach jeder Änderung der Netzwerk-Form neu walkst. Das nächste, was es wert ist, danach zu lesen, ist die Zeile oben, die du noch nicht gemacht hast. # Operations Source: https://tale.dev/docs/de/self-hosted/operate/observability/operations Die Operations-Seite ist das Alert-Playbook — welche Signale es wert sind, jemanden zu wecken, welche eine Kaffee-Runde überstehen können und wie die ersten fünf Minuten eines Vorfalls aussehen. Die Metrik-Oberfläche von Tale lebt hinter `METRICS_BEARER_TOKEN`; diese Seite nimmt an, dass du Prometheus und Grafana gemäss [Observability-Konfiguration](/de/self-hosted/configuration/observability-config) verdrahtet hast und jetzt wissen musst, welche Zahlen du beobachtest. Der symptomorientierte Index ist in [Troubleshooting](/de/self-hosted/operate/observability/troubleshooting). Diese Seite ist die proaktive Seite — Signale zuerst, Oncall-Checkliste zweitens. ## Signale, auf die zu alarmieren sich lohnt | Signal | Schweregrad | Warum es zählt | | ------------------------------------------- | ----------- | ---------------------------------------------------------- | | `tale-proxy`-Health-Probe scheitert > 1 Min | page | Jeder Benutzer sieht einen Verbindungsfehler | | `tale-platform` HTTP-5xx-Rate > 5 % | page | Die UI ist für einen relevanten Anteil der Anfragen kaputt | | `tale-convex` WebSocket-Reconnect-Storm | page | UI lädt, aber keine Daten fliessen | | Postgres-Verbindungen > 80 % des Pools | warn | Die nächste Spitze fängt an zu blockieren | | `db-data`-Volume > 80 % voll | warn | Das operative Postgres geht bei voll auf read-only | | `knowledge-db-data`-Volume > 80 % voll | warn | Ingestion scheitert, wenn die Korpus-Datenbank voll ist | | `tale-knowledge-db` von convex unerreichbar | warn | Wissens-Suche liefert leer; Ingestion stockt | | Anbieter-Anfrage-Fehlerrate > 20 % | warn | Der Upstream-LLM-Anbieter hat einen schlechten Tag | | Tägliches Backup nicht geschrieben | page | Restore-Drill scheitert zum schlimmsten Zeitpunkt | | TLS-Cert-Erneuerung gescheitert | warn | Erneuert 30 T vor Ablauf — du hast Zeit | Die ersten zwei Pages sind die wirklich kundenwirksamen. Die warns fangen Trends, bevor sie ins Page-Gebiet kippen. ## Log-Signale, nach denen man greppen sollte Logs kommen über stdout pro Container, aufgefangen vom `json-file`-Driver von Docker. Die vier Phrasen, die konsistent Ärger bedeuten: - `panic` oder `unexpected error` in `tale-convex`-Logs — Convex-Action-Crash. - `decryption failed` in `tale-platform`-Logs — SOPS-age-Schlüssel-Mismatch mit der Datei auf Platte. - `429 Too Many Requests` wiederholt von einem Anbieter — Rate-Limit getroffen, Agents fangen an zu scheitern. - `connection refused` oder `ECONNREFUSED` zu `knowledge-db` in `tale-convex`-Logs — das Backend erreicht die Korpus-Datenbank nicht; Ingestion und Wissens-Suche scheitern. Leite diese als abgeleitete Alerts an deinen Aggregator weiter; die Metric-Endpoints zeigen sie nicht als Gauges. ## Oncall-Checkliste Wenn eine Page landet, folgen die ersten fünf Minuten jedes Mal derselben Form. 1. **Bestätige, dass der Alert echt ist.** Öffne `$SITE_URL` im Browser. Lädt die UI und Chat funktioniert, schaust du auf ein Metrik- oder Scraper-Problem, nicht ein kundenwirksames. 2. **Identifiziere den Container.** `docker compose ps` zeigt, welcher unhealthy ist; `docker compose logs --tail=200 <service>` zeigt den letzten Fehler. 3. **Starte den wahrscheinlichsten Schuldigen neu.** `docker compose restart <service>` löst einen überraschenden Anteil der Vorfälle — Prozess-Crashes, abgestandene File-Watcher, erschöpfte Verbindungs-Pools. Die Architektur ist gebaut, um einen einzelnen Container-Restart sauber zu überleben. 4. **Prüf Upstream-Anbieter.** `https://status.openai.com`, `https://status.anthropic.com`, etc. Brennt der Anbieter, scheitern Agents; Tale ist nicht die Ursache. 5. **Page die diensthabende Ingenieurin, wenn das benutzerwirksame Symptom nach einem Restart bleibt.** Nicht früher eskalieren — die meisten Vorfälle lösen sich in den ersten drei Schritten. ## Was Oncall nicht braucht Ein `tale-knowledge-db`-Ausfall ist ein warn, kein page. Der Web-Crawl-Plan absorbiert Stunden von Downtime ohne Benutzerwirkung, und die Dokument-Ingestion versucht es erneut, statt Arbeit zu verwerfen — Uploads sitzen in „indexing", bis die Korpus-Datenbank zurück ist. Die Wissens-Suche liefert in der Zwischenzeit leer, aber Chats, die kein Wissen abrufen, arbeiten weiter. Fang das im warn-Band und fix es zu Geschäftszeiten. ## Antwortzeit-SLAs Zwei Antwortzeit-Budgets werden als erstklassige Signale verfolgt: interaktive Dialog-Eingabe und langlaufende Operationen wie Evaluierungen. Beide werden als **Mittelwert** über ein gleitendes Fenster verifiziert — die vertragliche Zahl ist ein Durchschnitt, keine Obergrenze pro Anfrage — und beide sind so verdrahtet, dass Prometheus alarmiert, sobald der Durchschnitt über das Budget driftet. | Budget | Statistik | Ziel | Fenster | Zugrundeliegende Serie | | --------------- | ---------- | ----- | ------- | ----------------------------- | | Dialog-Eingabe | Mittelwert | ~1 s | 30 Min | `tale_dialog_ttft_seconds` | | Lange Operation | Mittelwert | ~40 s | 6 Std | `tale_long_operation_seconds` | Jedes Ziel reitet zudem auf dem Plattform-Metrik-Endpoint als `tale_sla_target_seconds{sla,statistic}`, sodass ein Grafana-Panel die Budget-Linie direkt aus Prometheus zeichnet, statt sie fest zu verdrahten. Die zugrundeliegenden Latenz-Serien sind die Convex-Funktions-Ausführungs-Histogramme auf `/metrics/convex`; relabel oder record sie auf die Namen oben, damit die Rules auflösen. Die Plattform liefert die fertigen Recording- und Alerting-Rules unter `/metrics/sla-rules` (hinter demselben Bearer-Token wie die anderen Metrik-Pfade) — hole sie einmal und referenziere die Datei unter `rule_files:`, oder füge das Äquivalent ein: ```yaml groups: - name: tale-sla-recording rules: - record: tale_sla_dialog_ttft:mean30m expr: rate(tale_dialog_ttft_seconds_sum[30m]) / rate(tale_dialog_ttft_seconds_count[30m]) labels: sla: dialog_ttft - record: tale_sla_long_operation:mean6h expr: rate(tale_long_operation_seconds_sum[6h]) / rate(tale_long_operation_seconds_count[6h]) labels: sla: long_operation - name: tale-sla-alerts rules: - alert: TaleSlaDialogTtftBreached expr: tale_sla_dialog_ttft:mean30m > 1 for: 15m labels: severity: warn sla: dialog_ttft annotations: summary: 'Dialog input response time: mean response time over 30m exceeds the 1s SLA' description: Mean time-to-first-token for an interactive chat / dialog turn. - alert: TaleSlaLongOperationBreached expr: tale_sla_long_operation:mean6h > 40 for: 30m labels: severity: warn sla: long_operation annotations: summary: 'Long operation response time: mean response time over 6h exceeds the 40s SLA' description: Mean end-to-end time for long-running operations such as evaluations. ``` Ein Breach hier ist ein **warn**, kein page: ein driftender Durchschnitt ist eine Degradation, die zu Geschäftszeiten zu verfolgen ist, und die `for:`-Fenster warten bewusst eine kurze Spitze aus, bevor sie feuern. Das ~1-s-Dialog-Budget versöhnt sich mit dem lockereren ~3-s-Warm-Time-to-First-Token im manuellen Performance-Plan — jene ~3 s sind eine Obergrenze pro Anfrage für ein einzelnes kaltes, Auto-geroutetes erstes Token inklusive Modell- und Netzwerk-Zeit, während die ~1 s hier der Steady-State-Mittelwert über Dialog-Turns ist, sodass gelegentliche erste Tokens, die die Obergrenze erreichen, mit einem Sub-Sekunden-Mittelwert vereinbar sind. Den 1-s-Mittelwert auf Live-Anbietern zu halten, kann noch die Backend-Overhead-Optimierung brauchen, die im Feature-Issue verfolgt wird; dieser Alert bestätigt, ob das Ziel erreicht ist. ## Wo das hingehört Die Signale oben sind die proaktive Seite des Betreibens einer Tale-Instanz; die reaktive Seite ist [Troubleshooting](/de/self-hosted/operate/observability/troubleshooting), und die Konfiguration, die die Metriken in Prometheus bekommt, ist [Observability-Konfiguration](/de/self-hosted/configuration/observability-config). Hast du `METRICS_BEARER_TOKEN` noch nicht gesetzt, ist jede Schwelle oben unbeobachtet — fang dort an. # Troubleshooting Source: https://tale.dev/docs/de/self-hosted/operate/observability/troubleshooting Diese Seite ist das symptomorientierte Nachschlagen, wenn jetzt gerade etwas falsch ist. Jeder Abschnitt fängt mit dem an, was der Benutzer tatsächlich meldet — was der Browser zeigt, woran der Agent scheitert, was der Upload-Bildschirm sagt — und geht zurück zur Ursache und zum Fix. Alles, was hier nicht gelistet ist, ist ein Kandidat für einen neuen Abschnitt, sobald es zweimal aufgetaucht ist. Die proaktive Seite — Signale, auf die zu alarmieren sich lohnt, was in Prometheus zu verdrahten ist — lebt in [Operations](/de/self-hosted/operate/observability/operations). Diese Seite ist für den Moment, nachdem die Page gefeuert hat. ## Browser sieht 502 oder „Bad Gateway" Der `tale-proxy`-Container hat die Plattform erreicht, aber die Plattform hat nicht geantwortet. Entweder ist `tale-platform` down oder sein Health-Endpoint unerreichbar. Prüf zuerst den Container-Zustand: ```bash docker compose ps tale-platform docker compose logs --tail=200 tale-platform ``` Startet der Container neu, zeigen die Logs am Boden den Crash-Grund — meist eine fehlkonfigurierte Env-Var (`SITE_URL`-Mismatch, fehlender `BETTER_AUTH_SECRET`) oder ein Postgres-Verbindungsfehler. Fix die Env, starte neu, versuche es erneut. Ist der Container healthy, aber der Browser sieht immer noch 502, ist der Proxy der Verdächtige — `docker compose restart tale-proxy` räumt die meisten davon weg. ## Browser sieht eine TLS-Warnung `TLS_MODE=selfsigned` ist die häufigste Ursache — der Browser vertraut der internen CA von Caddy beim ersten Besuch nicht. Vertrau entweder der CA auf dem Host (`docker exec tale-proxy caddy trust`) oder wechsel zu `TLS_MODE=letsencrypt` für ein echtes Zertifikat. Der vollständige Modus-Walk lebt in [TLS und Domains](/de/self-hosted/configuration/tls-and-domains). Ist der Modus bereits `letsencrypt`, prüf die Proxy-Logs auf ACME-Fehlschläge — DNS löst nicht auf die öffentliche IP des Hosts und Port 80 ist vom öffentlichen Internet nicht erreichbar sind die zwei häufigen Ursachen. ## UI lädt, aber keine Daten erscheinen Die UI-Shell sind statische Assets, von `tale-platform` serviert; alles andere fliesst durch `tale-convex` über einen WebSocket. Wenn der WebSocket sich nicht verbinden kann, lädt die Shell und bleibt leer. Symptome: Spinner, die nie auflösen, „reconnecting"-Toasts, der Chat-Input, der nie eine Nachricht annimmt. ```bash docker compose logs --tail=200 tale-convex ``` Der Convex-Container startet wahrscheinlich neu (such nach `panic` in den Logs) oder ist vom Proxy unerreichbar. Starte mit `docker compose restart tale-convex` neu — Sessions sind serverseitig, und Clients reabonnieren beim Reconnect, also ist der Restart sicher. ## Uploads stecken in „indexing" Die Dokument-Ingestion läuft im Convex-Backend und schreibt die extrahierten Chunks und Embeddings in die Datenbank des Wissens-Korpus. Ein langer „indexing"-Zustand bedeutet entweder, dass das Backend `tale-knowledge-db` nicht erreicht oder dass die Datei selbst nicht extrahiert werden konnte. Prüf zuerst die Convex-Logs und die Korpus-Datenbank: ```bash docker compose logs --tail=200 tale-convex | grep -iE "knowledge|ingest|embed" docker compose ps tale-knowledge-db ``` Zeigen die Logs Verbindungsfehler zu `knowledge-db`, starte die Korpus-Datenbank neu (`docker compose restart tale-knowledge-db`); die Ingestion versucht es beim nächsten Durchlauf erneut, Uploads müssen also nicht erneut eingereicht werden. Ist die Datenbank healthy, aber ein bestimmter Upload steckt, ist die Datei selbst der Verdächtige — beschädigte PDFs und passwortgeschützte Dokumente landen in einem Fehlzustand und brauchen Löschung und Re-Upload. ## Chat-Antworten hören mitten im Stream auf Der Token-Stream vom Upstream-Anbieter ist abgefallen — entweder hat der Anbieter rate-limited, die Verbindung ist getimeoutet, oder der Service des Anbieters ist degradiert. Prüf zuerst die Status-Seite des Anbieters; schau dann in die Plattform-Logs: ```bash docker compose logs --tail=200 tale-platform | grep -E "429|503|stream" ``` Ein `429` ist der häufige Fall. Entweder trifft das Budget der Org das Rate-Limit des Anbieters, oder der Anbieter-Schlüssel selbst ist gedrosselt. Das Default-Modell der Org auf einen weniger ausgelasteten Anbieter umzuschalten räumt das Symptom weg, während das Upstream abkühlt. ## Speichern scheitert mit „saving failed"-Toast Der Convex-Container konnte nicht in Postgres schreiben. Entweder ist `tale-db` down oder seine Platte ist voll: ```bash docker compose ps tale-db docker compose exec db df -h /var/lib/postgresql/data ``` Eine Platte bei 100 % ist der Fehler, der die meisten überraschten Gesichter erzeugt. Schaff Platz, starte `tale-db` neu, und die gepufferten Writes flushen. Hat die Platte Platz, ist der Verdächtige Verbindungs-Pool-Erschöpfung oder ein Lock — starte `tale-convex` neu, um den Pool zu räumen. ## „Run code"-Tool scheitert mit „egress denied" Der `tale-sandbox-egress`-Container ist der einzige ausgehende Netzwerk-Pfad für sandboxierten Code; ist er down oder fehlkonfiguriert, scheitert jede ausgehende Anfrage aus der Sandbox geschlossen. Prüf zuerst den Egress-Container: ```bash docker compose ps tale-sandbox-egress docker compose logs --tail=100 tale-sandbox-egress ``` Ist der Container healthy und du hast `SANDBOX_EGRESS_ALLOWLIST` gesetzt, hat die Anfrage die Allowlist getroffen — erweitere die Variable in `.env` und erzeuge `tale-sandbox-egress` neu. Ohne Allowlist ist der Proxy auf Hostname-Ebene offen; prüf stattdessen das Ziel: für HTTPS wird nur Port 443 getunnelt, und Cloud-Metadaten-Adressen sowie private Adressbereiche sind auf IP-Ebene immer blockiert. ## Sign-in läuft zurück in die Sign-in-Seite `SITE_URL` passt nicht zu dem, was der Browser tatsächlich angefragt hat. Auth-Cookies sind auf die URL gescopt, auf der die Anfrage landete; ein Mismatch (Trailing Slash, fehlender Port, `http` vs `https`, Base-Path-Präfix) bedeutet, dass das beim Callback gesetzte Cookie bei der nächsten Anfrage nicht mitgeschickt wird. Fix `.env`: ```bash SITE_URL=https://tale.example.com # exakt, was der Benutzer tippt ``` Erstell den Plattform-Container neu (`docker compose up -d --force-recreate tale-platform`), damit die Änderung im gerenderten HTML landet. ## Wo du Hilfe bekommst Self-hosted-Instanzen telefonieren nicht heim, also fängt Support bei dir an. Die zwei Kanäle: - **GitHub Issues** — Bugs und reproduzierbare Probleme. Der [tale-project/tale](https://github.com/tale-project/tale/issues)-Tracker hat ein Template, das nach dem Diagnose-Bundle fragt, das `tale diagnostics` produziert. - **Discord** — Fragen, Konfigurations-Debatten, „ist das ein Bug"-Triage. Die Einladung lebt im Repo-README. Reproduzierbare Diagnose macht jeden Kanal schneller. `tale diagnostics` sammelt sanitised Logs, Env-Vars (Secrets redigiert) und Container-Health in ein einzelnes Archiv, das es wert ist, angehängt zu werden. # Prometheus und Grafana Source: https://tale.dev/docs/de/self-hosted/operate/observability/prometheus-grafana Das ist das durchgespielte Beispiel hinter [Observability-Konfiguration](/de/self-hosted/configuration/observability-config): ein Paar aus Prometheus und Grafana, das du neben Tale stellst, auf die zwei Bearer-Token-Metrics-Endpoints gerichtet, mit einem Starter-Dashboard und einer Alert-Regel zum Ausbauen. Es ist für selbst hostende Betreiber, die `METRICS_BEARER_TOKEN` bereits gesetzt haben und jetzt Live-Graphen statt eines `curl` gegen `/metrics` wollen. Die Konfigurations-Referenzseite listet die Endpoints und die einzelne Scrape-Stanza; diese Seite stellt den ganzen Stack von Anfang bis Ende auf. Alles hier läuft auf demselben Host wie Tale, also verlässt keine Metrik die Maschine. ## Bevor du startest Setz `METRICS_BEARER_TOKEN` in deiner `.env` und starte den Proxy neu — ohne ihn geben die zwei Endpoints auf jede Anfrage 401 zurück, und Prometheus zeigt jedes Target als down. Die Endpoints, und was jeder trägt, sind die Tabelle in [Observability-Konfiguration](/de/self-hosted/configuration/observability-config#metrics): `/metrics/platform` und `/metrics/convex` (Letzterer trägt jetzt die In-Process-RAG- und Crawl-Timings), beide von `tale-proxy` über denselben Hostnamen wie die App ausgeliefert. ## Prometheus und Grafana zu deinem Stack hinzufügen Leg diese zwei Services in ein Compose-Override neben Tale. Prometheus scrapt in einem Intervall und speichert eine lokale TSDB; Grafana liest Prometheus und rendert die Dashboards. Beide binden nur an localhost — erreich Grafana über einen SSH-Tunnel oder stell es mit Auth hinter denselben Proxy, exponier es nie roh. ```yaml # docker-compose.metrics.yml — start with: docker compose -f docker-compose.yml -f docker-compose.metrics.yml up -d services: prometheus: image: prom/prometheus:v3.1.0 volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro - prometheus-data:/prometheus ports: - '127.0.0.1:9090:9090' restart: unless-stopped grafana: image: grafana/grafana:11.4.0 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 volumes: prometheus-data: grafana-data: ``` ## Scrape-Konfiguration Tales zwei Endpoints teilen sich ein Bearer-Token, also ist die Scrape-Konfiguration die veröffentlichte Stanza, einmal pro Pfad wiederholt. Speicher das als `prometheus.yml` neben dem Override oben und setz deinen Host und dein Token ein — Prometheus liest das Token aus der Datei, also halt sie `chmod 600` und aus der Versionskontrolle raus. ```yaml global: scrape_interval: 30s scrape_configs: - job_name: tale-platform scheme: https metrics_path: /metrics/platform authorization: { credentials: '${METRICS_BEARER_TOKEN}' } static_configs: - targets: ['tale.example.com'] - job_name: tale-convex scheme: https metrics_path: /metrics/convex authorization: { credentials: '${METRICS_BEARER_TOKEN}' } static_configs: - targets: ['tale.example.com'] ``` Öffne `http://127.0.0.1:9090/targets` nach dem Start — beide Jobs sollten **UP** anzeigen. Ein Target, das mit 401 auf **DOWN** hängt, heisst, das Token in `prometheus.yml` stimmt nicht mit `METRICS_BEARER_TOKEN` überein; ein Verbindungsfehler heisst, Hostname oder Schema sind falsch. ## Ein Starter-Dashboard Richte Grafana zuerst auf Prometheus — füg eine Prometheus-Datenquelle unter `http://prometheus:9090` hinzu (Grafana erreicht sie über den Compose-Servicenamen). Bau dann ein Dashboard aus diesen Panels; die ersten drei nutzen Metriken, die immer vorhanden sind, und der Rest bildet die Signale in [Operations](/de/self-hosted/operate/observability/operations) ab. | Panel | Query | Liest sich als | | --------------- | ---------------------------------------------------- | ------------------------------------------------------------ | | Targets up | `up{job=~"tale-.*"}` | `1` pro gesundem Endpoint, `0` wenn das Scraping fehlschlägt | | Platform-Memory | `process_resident_memory_bytes{job="tale-platform"}` | Resident-Memory des platform-Containers | | Event-Loop-Lag | `nodejs_eventloop_lag_seconds{job="tale-platform"}` | Springt, wenn die Plattform gesättigt ist | | Convex up | `up{job="tale-convex"}` | Backend-Erreichbarkeit — `0` ist ein Page | Der platform-Endpoint trägt Nodes Default-Prozessmetriken (CPU, Memory, Event-Loop-Lag, GC), darum zielen die konkreten Queries oben auf ihn. Der Convex-Endpoint exponiert seine eigene reichere Reihe, inklusive der In-Process-RAG- und Crawl-Timings — öffne ihn einmal (`curl -H "Authorization: Bearer $TOKEN" https://tale.example.com/metrics/convex`), um die exakten Metriknamen deiner Version zu lesen, und füg dann Panels für den Wissens-Ingestion-Durchsatz und die Provider-Fehlerrate aus Operations hinzu. ## Eine erste Alert-Regel Fang mit dem einen Signal an, das eindeutig ist — ein Metrics-Target, das aufhört zu antworten. Füg diese Regel-Datei zu Prometheus hinzu (mounte sie und referenzier sie unter `rule_files:` in `prometheus.yml`), dann verdrahte Alertmanager oder Grafana-Alerting mit deinem Pager. ```yaml 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' ``` Die volle Liste, was ein Page wert ist gegenüber was warten kann — platform-5xx-Rate, Postgres-Pool-Sättigung, Erreichbarkeit der Wissensdatenbank, tägliches-Backup-nicht-geschrieben — ist die Signaltabelle in [Operations](/de/self-hosted/operate/observability/operations); übersetz jede Zeile in eine Regel, sobald die passende Reihe auf deinem Dashboard ist. ## Wo das hingehört Diese Seite verwandelt die zwei dokumentierten Metrics-Endpoints in einen laufenden Prometheus-und-Grafana-Stack: ein Compose-Override, eine Zwei-Job-Scrape-Konfiguration, ein Starter-Dashboard und einen Target-down-Alert, den du mit den Operations-Schwellen ausbaust. Halt beide Services an localhost gebunden und das Bearer-Token nicht im Klartext auf der Festplatte, und die ganze Monitoring-Oberfläche bleibt mit Tale auf dem Host. Die Endpoints und das Token, das sie absichert, gehören [Observability-Konfiguration](/de/self-hosted/configuration/observability-config); die Schwellen und die Oncall-Checkliste sind [Operations](/de/self-hosted/operate/observability/operations). Wenn ein Panel rot wird, ist die Symptom-zu-Fix-Suche [Troubleshooting](/de/self-hosted/operate/observability/troubleshooting). # Upgrades Source: https://tale.dev/docs/de/self-hosted/operate/upgrades Upgrades auf einer self-hosted Tale-Instanz laufen durch zwei Kommandos: `tale update` bewegt das CLI-Binary auf die neue Version und synct deine Projektdateien passend dazu, dann rollt `tale deploy` die Plattform-Container. Der Deploy nutzt ein Blue-Green-Pattern — die neue Farbe startet neben der alten, Healthchecks bestehen, der Traffic kippt, die alte Farbe drainet. Zero-Downtime ist der Default; macht ein Patch-Release Ärger, bringt `tale rollback` den vorherigen Patch in einem Kommando zurück, und alles Größere recovert aus dem Pre-Upgrade-Snapshot. Was du nicht mehr tust, ist das CLI von Hand im Gleichschritt zu halten: Das CLI gleicht sich automatisch an die Instanz an (siehe unten), sodass der einzige bewusste Schritt die Wahl ist, wann du mit `tale update` die Version wechselst. Die CLI-Installation lebt in [Tale-CLI installieren](/de/self-hosted/install/cli-install). Diese Seite deckt ab, was jedes Kommando tut und wie das Versions-Modell funktioniert. ## Das CLI verfolgt die Instanz automatisch Das CLI-Binary hat immer dieselbe Version wie die Instanz, die es verwaltet. Der Workspace zeichnet diese Version in `tale.json` auf; bei jedem Kommando vergleicht das CLI seine eigene Version dagegen und aktualisiert sich selbst — auf- oder abwärts —, falls sie sich unterscheiden, bevor es läuft. Stimmen sie schon überein — der ganz überwiegend häufige Fall —, ist das ein No-op ohne Netzwerk-Aufruf, sodass du nie etwas davon merkst. Das heißt, du läufst `tale update` selten, außer wenn du bewusst auf eine neue Version willst. Ein Teamkollege, der ein neueres CLI als deine Instanz installiert hat, oder einen älteren Snapshot wiederhergestellt hat, bekommt beim nächsten Kommando automatisch die richtige CLI-Version. Es gibt kein Flag, das abzuschalten — Tool und Instanz im Gleichschritt zu halten ist das, was Deploys sicher macht. ## Bevor du upgradest Zwei Dinge sind es wert, zuerst zu bestätigen: - Deine Off-Host-Kopie des `backups`-Volumes ist aktuell — siehe [Backups und Restore](/de/self-hosted/operate/backups-and-restore). `tale update` snapshotet die Daten-Volumes automatisch vor jedem Schritt, der Daten migrieren kann, aber der Snapshot lebt auf demselben Host; die Off-Host-Kopie ist das, was eine tote Platte überlebt. - Die Release-Notes für die Zielversion nennen keinen breaking Change. Die Notes sind von der GitHub-Release-Seite verlinkt; breaking Changes sind oben als solche markiert. Überschreitet das Upgrade eine Major-Version (1.x → 2.x), lies die Migrations-Notes End-to-End, bevor du anfängst. Major-Versionen sind, wo Schema-Migrationen und Config-Datei-Format-Änderungen landen. ## Die zwei Kommandos `tale update` aktualisiert das CLI-Binary und synct dann deine Projektdateien auf die Templates dieser Version. Es fasst die laufenden Container **nicht** an — das ist der Job von `tale deploy`. Scheitert der Datei-Sync, rollt das CLI sein eigenes Binary auf die Version zurück, auf der dein Workspace war, sodass Binary und `tale.json` nie auseinanderdriften. ```bash # Bewege das CLI und die Projektdateien auf das letzte Release tale update # Eine bestimmte Version festnageln (erlaubt Downgrades — siehe Zurückrollen) tale update --version 0.10.2 # Versions-Wechsel und Datei-Sync vorab ansehen, ohne etwas anzufassen tale update --dry-run ``` `tale deploy` macht den eigentlichen Rolling-Restart und deployt immer die eigene Version des CLI — die dank der Angleichung die Version ist, die dein Workspace aufzeichnet. Es sortiert die Services in drei Tiers: - **App-Tier** — `platform` — rollt bei **jedem** Deploy ohne Downtime (Blue-Green: die neue Farbe startet neben der alten, Healthchecks bestehen, der Traffic kippt, die alte Farbe drainet). - **Backend und Compute** — `convex`, `sandbox`, `sandbox-egress` — rollen ebenfalls bei jedem Deploy, sodass sie nie gegenüber `platform` versions-skewen. Jeder ist ein einzelner Container, der sich **in-place** neu erstellt, wenn sich sein Image tatsächlich geändert hat; der Deploy drainet zuerst die laufende Arbeit (Chat-Generierungen bei `convex`, Agent-Runs bei `sandbox`), damit der kurze Neustart keine lebende Anfrage abschneidet. - **Stop-gegateter Tier** — `db`, `proxy` — bleibt standardmäßig **laufend und unangetastet** (Postgres oder den Proxy neu zu erstellen ist eine kurze Ausfallzeit, die du bei einem Routine-Roll nicht willst). Mit `--stop` aktualisierst du sie; der Deploy warnt und nennt sie, wenn er sie überspringt. ```bash # Nach tale update die Container passend rollen (App-Tier + convex) tale deploy # Auch db/proxy aktualisieren (kurze Downtime, während sie neu erstellt werden) tale deploy --stop # Nur bestimmte Services rollen tale deploy --services platform # Vorschau ohne Änderungen tale deploy --dry-run ``` `--dry-run` ist es wert, vor jedem Produktions-Upgrade zu laufen — es bringt fehlende Images, fehlende Migrationen und Dependency-Mismatches zum Vorschein, ohne die laufenden Container zu berühren. ## Das Blue-Green-Pattern Eine laufende Instanz ist zu jeder Zeit eine der zwei Farben (Blue oder Green). Die Deploy-Phase bringt die andere Farbe hoch, wartet, bis sie Healthchecks besteht, und kippt dann Caddys Upstream auf die neue Farbe. Die alte Farbe drainet ihre in-flight-Anfragen (Default 30 s), dann beendet sie sich. Drei Garantien, die das Pattern dir gibt: - **Kein Fenster, in dem beide Farben Traffic servieren.** Ein Datenbank-Constraint setzt single-active durch — Caddy routet zur gesunden. - **Patch-Rollback ist ein Kommando.** `tale rollback` deployt das vorherige Patch-Release auf der inaktiven Farbe neu und kippt den Traffic zurück. Minor- und Major-Downgrades verweigert es — die können die Datenbank vor dem Binary zurücklassen, und ihr Recovery-Pfad ist ein Snapshot-Restore. - **Gescheiterte Healthchecks blockieren den Kipp.** Besteht die neue Farbe nicht innerhalb des Timeouts, bricht der Deploy ab und die alte Farbe serviert weiter. Die vollständige Deploy-Prozedur inklusive der Cleanup-Phase lebt in `tale --help`; das operatorseitige Rezept ist `tale update && tale deploy && tale status` und visuelle Bestätigung im Browser. ## Mit Datenmigrationen arbeiten Jedes Deploy wendet ausstehende Datenmigrationen automatisch an — aber nur die nicht-destruktiven. Migrationen, die Daten entfernen oder überschreiben (ein Tabellen-Drop, eine entfernte Spalte), laufen nie unbeaufsichtigt: Das Deploy überspringt sie, listet auf, welche warten, und überlässt dir die Entscheidung. ```bash # Was angewendet ist, was aussteht, was fehlgeschlagen ist tale migrate status # Ausstehende Migrationen anwenden, jeden destruktiven Schritt einzeln prüfen tale migrate up --step # Alles ohne Rückfragen anwenden (CI / nach Prüfung des Plans) tale migrate up --yes # Daten auf eine frühere Version zurückrollen tale migrate down --to 0.3.3 ``` Destruktive Migrationen sichern die betroffenen Zeilen bzw. Konfigurationsdateien, bevor sie sie anfassen — `tale migrate down` kann so wiederherstellen, was sie entfernt haben. Beide Richtungen sind fortsetzbar: Der Fortschritt wird pro Migration festgehalten (bei Konfigurationsdatei-Migrationen pro Organisation), ein Absturz oder Timeout setzt also dort wieder an, wo er unterbrochen wurde. Schlägt eine Migration während eines Deploys fehl, bootet die Plattform trotzdem auf ihrem aktuellen Schema — das Boot-Log zeigt einen deutlichen Fehler, und `tale migrate status` nennt die fehlgeschlagene Migration samt Fehlermeldung. Ursache beheben, dann `tale migrate up` erneut ausführen; bereits erledigte Arbeit wird übersprungen. ## Zurückrollen ```bash # Zurück zur vorherigen Patch-Version (fragt nach Bestätigung) tale rollback # Die Abfrage im nicht-interaktiven Betrieb überspringen tale rollback --yes ``` `tale rollback` ist auf Patch-Schritte begrenzt: Es zielt nur auf die aufgezeichnete vorherige Version und verweigert, wenn diese Version nicht `major.minor` mit der laufenden Plattform teilt. Patch-Releases tragen nie Migrationen, also ist das Redeploy des vorherigen Patches immer sicher. Alles Größere kann Daten vorwärts migriert haben — ein älteres Binary auf migrierten Daten zu deployen korrumpiert die Instanz, statt sie zu retten. Für diese Fälle ist der Recovery-Pfad, den Pre-Upgrade-Snapshot wiederherzustellen und mit `tale update --version <version>` gefolgt von `tale deploy --stop` (sodass `db`/`proxy` ebenfalls zurückrollen) auf die passende Version zurückzugehen; die Verweigerungs-Meldung druckt die exakten Kommandos, und der volle Walk lebt in [Backups und Restore](/de/self-hosted/operate/backups-and-restore). Weil das Zurückrollen die laufenden Container abräumt, warnt das Kommando, was es vorhat, und fragt nach Bestätigung, bevor es auch nur ein Image zieht; mit `--yes` überspringst du diese Abfrage in Skripten oder CI. ## Versions-Kompatibilität Tale-Versionen sind semver. Die Kompatibilitäts-Regeln: - Patch (`0.9.0 → 0.9.1`) — keine Migrationen, keine Config-Änderungen, `tale rollback` ist immer sicher. - Minor (`0.9.x → 0.10.x`) — kann forward-only Migrationen enthalten; `tale rollback` verweigert, Recovery ist Snapshot-Restore plus Redeploy. - Major (`0.x → 1.x`) — lies die Migrations-Notes, plan das Wartungsfenster, erwarte Überraschungen. Minor-Versionen zu überspringen (von 0.9 auf 0.11 zu gehen) ist unterstützt, solange die Zwischen-Migrationen noch im Binary sind; die Release-Notes nennen es, wenn das nicht der Fall ist. Um bewusst eine Version _runter_ zu gehen — etwa wenn ein Minor-Release Ärger macht und du seine Migrationen schon zurückgenommen hast —, nagle das Ziel mit `tale update --version <version>` fest. Das Kommando warnt, wenn das Ziel älter als die laufende Version ist, und erinnert dich, zuerst die Daten-Migrationen zurückzunehmen. ## Upgrade von 0.3.1 oder älter Instanzen auf Version 0.3.1 oder älter halten die Daten des Convex-Backends im Docker-Volume `platform-data`. Neuere Versionen betreiben Convex als eigenen Service mit eigenem `convex-data`-Volume — und beim Deploy zieht nichts die Daten automatisch um. Springst du direkt über diese Grenze, legt `tale deploy` ein **leeres** `convex-data`-Volume an: Die Instanz kommt leer hoch, während jedes Byte deiner Daten unangetastet im alten `platform-data`-Volume liegt. Gelöscht wird nichts — aber die Daten ziehen nicht von selbst um, und `tale update` warnt, wenn es diese Konstellation erkennt, und bietet dir an, die Kopie direkt auszuführen. Docker kennt kein natives Volume-Rename, der Umzug ist also eine Kopie durch einen Helfer-Container — genau die Schritte, die `tale update` für dich ausführt, wenn du den Prompt bestätigst (das alte Volume bleibt in jedem Fall erhalten). Von Hand — weil du den Prompt abgelehnt hast oder die automatische Kopie fehlgeschlagen ist — führst du ihn vor `tale deploy` aus, mit gestopptem Stack, damit nichts das Volume offen hält: ```bash # 1. Das Legacy-Volume finden — <project> ist die `id` in tale.json. docker volume ls | grep platform-data # Installationen älter als 0.2.33 nutzten das feste Präfix `tale_` # statt `<project>_`; das Ziel unten nutzt weiterhin `<project>_`. # 2. Den laufenden Stack stoppen. docker compose -p <project> down # 3. Ziel-Volume anlegen und die Daten hinüberkopieren. docker volume create <project>_convex-data docker run --rm \ -v <project>_platform-data:/from:ro \ -v <project>_convex-data:/to \ alpine sh -c "cd /from && cp -a . /to" # 4. Stack rollen, dann prüfen, dass deine Daten da sind. tale deploy # 5. Erst nach dem Prüfen das alte Volume freigeben. docker volume rm <project>_platform-data ``` Ein Dev-Workspace spiegelt denselben Umzug unter dem `-dev`-Scope: `<project>-dev_platform-data` → `<project>-dev_convex-data`, mit `docker compose -p <project>-dev down` als Stopp-Schritt. Hast du schon deployt und eine leere Instanz bekommen, sind deine Daten weiterhin sicher in `platform-data`. Stoppe den Stack, entferne das frisch angelegte leere Volume mit `docker volume rm <project>_convex-data`, führ dann die Kopie oben aus und deploye erneut. ## Wo das hingehört Der Upgrade-Flow knüpft jede andere Operate-Seite an — Backups sind das, was ein gescheitertes Upgrade wiederherstellbar macht, Observability ist das, was dir sagt, dass die neue Farbe healthy ist, Hardening ist das, was du nach einer Major-Version neu durchgehst. Setzt du das CLI zum ersten Mal auf, deckt [Tale-CLI installieren](/de/self-hosted/install/cli-install) das workstationseitige Setup ab; nimmst du den Pager mitten im Rollout auf, nennt [Troubleshooting](/de/self-hosted/operate/observability/troubleshooting) die Symptome. # Datenresidenz Source: https://tale.dev/docs/de/self-hosted/configuration/data-residency Eine selbst gehostete Tale-Installation läuft auf Infrastruktur, die du ohnehin schon kontrollierst, also liegen ihre Daten standardmäßig auf deinen Hosts. **Datenresidenz** ist für den Fall gedacht, dass du einzelne Datenspeicher auf dein eigenes verwaltetes Postgres oder deinen Objektspeicher ausrichten willst statt auf die mitgelieferten Container — etwa um Dokumenttext in einer Datenbank zu halten, die dein Team betreibt, oder hochgeladene Dateien in deinem eigenen S3-Bucket. Der Wissens-Korpus läuft genau deshalb als eigener Container (`knowledge-db`), damit er sich unabhängig von der operativen Datenbank verlagern oder ersetzen lässt — er ist der Speicher, um den sich die meisten Residenz-Anforderungen drehen. Administratoren konfigurieren das unter **Einstellungen > Datenresidenz**; die Änderung wird in eine einzige Konfigurationsdatei auf Deployment-Ebene geschrieben und **greift, sobald die betroffenen Container neu starten**. Diese Seite behandelt, was sich verlagern lässt, die eine Voraussetzung, die zubeißt (ParadeDB), wie die Konfiguration abgelegt und angewendet wird, und wie du sicher neu startest. ## Bearbeitung aktivieren Die Seite ansehen darf jeder Owner oder Admin einer Organisation, aber **bearbeiten** — einen Datenspeicher umlenken, Secrets speichern, einen Verbindungstest laufen lassen oder einen Neustart auslösen — darf nur eine benannte Allowlist von Operatoren. Trage deren Anmelde-E-Mails (kommagetrennt) in `.env` ein und starte neu: ```bash TALE_DEPLOYMENT_CONFIG_ADMINS=alice@example.com,bob@example.com ``` Ist die Allowlist leer oder nicht gesetzt, zeigt **Einstellungen > Datenresidenz** Administratoren die aktuelle Konfiguration weiterhin an, aber nur lesend — Speichern, Testen und Anwenden & neu starten verweigern für alle den Dienst. Nur ein angemeldeter Admin, dessen E-Mail auf der Liste steht, bekommt eine bearbeitbare Seite; die Seite nennt dir, welche E-Mail einzutragen ist. Die Entrypoints lesen die Konfigurationsdatei unabhängig von der Allowlist, also kann ein Operator, der die Datei lieber direkt auf der Platte bearbeitet, das tun, ohne UI-Bearbeiter zu benennen. ## Was du verlagern kannst Drei Speicher, jeder unabhängig und optional. Eine fehlende Einstellung bedeutet „nimm den mitgelieferten Default" — eine frische Installation ohne Konfiguration bleibt also unverändert. - **Wissensdatenbank** — der Wissens-Korpus: Dokumentmetadaten, der extrahierte Chunk-Text, Embeddings, der BM25-Index, der semantische Cache und die gecrawlten Webseiten. Sie kommt als mitgelieferter `knowledge-db`-Container (`tale_knowledge`, mit den Schemata `private_knowledge` und `public_web`) und ist der Speicher, um den sich die meisten Residenz-Anforderungen drehen, weil er deinen Dokumentinhalt hält. Richte ihn auf dein eigenes verwaltetes Postgres aus, um den Korpus auf Infrastruktur zu halten, die dein Team betreibt. - **Dateispeicher** — wo hochgeladene Dateien (die ursprünglichen Blobs) liegen. Standardmäßig sitzen sie auf dem lokalen Convex-Volume; du kannst sie auf einen externen S3-kompatiblen Bucket ausrichten. - **Anwendungsdatenbank** (erweitert) — die operative Convex-Datenbank (der mitgelieferte `db`-Container). Das Convex-Backend leitet den Namen dieser Datenbank aus `INSTANCE_NAME` (`tale_platform`) ab und verbindet sich nur über Host:Port, daher muss das externe Postgres eine Datenbank mit genau dem Namen `tale_platform` enthalten. Ihr TLS-Modus wird vom Convex-Treiber vorgegeben und ist nicht konfigurierbar. > Hinweis: Die Wissensdatenbank und die Anwendungsdatenbank sind zwei separate Postgres-Instanzen — die eine zu verschieben rührt die andere nicht an. Die Wissensdatenbank zu verlagern verschiebt den extrahierten Text und die Embeddings; die ursprünglich hochgeladenen Dateien wandern erst mit, wenn du auch den **Dateispeicher** auf S3 ausrichtest. ## Die ParadeDB-Voraussetzung Die Wissensdatenbank nutzt zwei Postgres-Erweiterungen: `vector` (pgvector) für Embeddings und `pg_search` (ParadeDB) für die Volltext-/BM25-Hybrid-Suche. Ein externes Wissens-Postgres **muss ParadeDB ausführen** (das beide bündelt), damit die Suchqualität voll erhalten bleibt. Richtest du es auf ein schlichtes Postgres aus, das nur `pgvector` hat, funktionieren Indexierung und Vektor-Suche weiter, aber die Hybrid-Suche fällt auf **reine Vektor-Suche** zurück — die BM25-Hälfte wird still übersprungen. Der Knopf **Verbindung testen** meldet die Verfügbarkeit von `pgvector` und `pg_search`, damit du das siehst, bevor du dich festlegst. Die externe Wissensdatenbank muss bereits existieren (sie kann jeden Namen tragen, den du einträgst — `tale_knowledge` per Konvention) mit den Schemata `private_knowledge` und `public_web`; die Baseline-Schema-Migrationen leben in [`services/db/migrations/`](https://github.com/tale-project/tale/tree/main/services/db/migrations) und werden per dbmate angewendet, wenn die Datenbank hochkommt. ## Dateispeicher auf S3 Externer Dateispeicher ist alles-oder-nichts über die Speicher-Use-Cases von Convex hinweg, also gibst du **fünf Buckets** an — files, exports, snapshot-imports, modules und search — plus Region und Anmeldedaten. Für S3-kompatible Dienste (MinIO, Cloudflare R2) setzt du den Endpunkt und aktivierst die Path-Style-Adressierung. > **Nur Greenfield.** Den Dateispeicher von lokal auf S3 umzustellen migriert die bereits auf dem lokalen Volume liegenden Blobs **nicht** — Convex sucht sie im Bucket und findet sie nicht. Setze S3 bei der ersten Installation, oder kopiere den vorhandenen lokalen Speicher vorab in den Bucket, bevor du umstellst. ## Wie die Konfiguration abgelegt wird Speichern schreibt zwei Dateien im Konfigurations-Root (nicht unter einem Org-Verzeichnis): - `deployment.json` — die nicht geheime Konfiguration (Hosts, Ports, Buckets, Modi). - `deployment.secrets.json` — die Datenbank-Passwörter und S3-Schlüssel, SOPS-verschlüsselt (siehe [Secrets mit SOPS](/de/self-hosted/configuration/secrets-with-sops)). Beim Boot liest der `convex`-Entrypoint diese und leitet seine Verbindungen ab, bevor er startet. Wissens-Ingestion und Retrieval laufen im Convex-Backend, also ist es der einzige Container, der die Verbindung zur Wissensdatenbank öffnet — es gibt keinen separaten Retrieval-Dienst zu konfigurieren. Der Vertrag ist **fail-closed**: ein vorhandenes, aber unparsbares `deployment.json`, ein nicht entschlüsselbares Secret oder eine Konfiguration ohne Pflichtfelder **bricht den Start ab**, statt still auf die mitgelieferte Datenbank zurückzufallen — regulierte Daten fehlzuleiten ist schlimmer, als nicht zu starten. Eine fehlende Datei ist der normale Default-Pfad. ## Eine Änderung anwenden: Neustart Die Konfiguration wird beim Boot gelesen, also greift ein Speichern erst, wenn der **`convex`**-Container neu startet (die Plattform selbst muss nicht neu starten). Zwei Wege: - **Manuell** — `docker compose restart convex`, oder `tale deploy --services convex` für einen Zero-Downtime-Blue-Green-Roll. - **Ein Klick** — aktiviere den Opt-in-Dienst `controller` (`docker compose --profile controller up -d`). Er ist ein kleiner, nur intern erreichbarer Sidecar, der den erlaubten `convex`-Dienst auf eine HMAC-signierte Anfrage der App neu startet, damit die browserzugewandte Plattform nie Docker-Socket-Zugriff braucht. Läuft er, erledigt der Knopf **Anwenden & neu starten** den Neustart für dich; setze `CONTROLLER_TOKEN` (geteilt mit der Plattform) und `CONTROLLER_URL` in `.env`. Ohne ihn zeigt der Knopf den manuellen Befehl. Die relevanten Umgebungsvariablen sind `TALE_DEPLOYMENT_CONFIG_ADMINS` (die kommagetrennte E-Mail-Allowlist der bearbeitungsberechtigten Operatoren) und — nur beim Ein-Klick-`controller` — `CONTROLLER_TOKEN` (das geteilte HMAC-Geheimnis) und `CONTROLLER_URL` (z. B. `http://controller:8004`). Setze sie in `.env`. Siehe auch [Umgebungsvariablen-Referenz](/de/self-hosted/configuration/environment-reference) und [Secrets mit SOPS](/de/self-hosted/configuration/secrets-with-sops). # TLS und Domains Source: https://tale.dev/docs/de/self-hosted/configuration/tls-and-domains Der `tale-proxy`-Container ist Caddy. Er besitzt die TLS-Terminierung, das Host-Routing und das Metric-Auth-Gate; jede Browser-seitige Anfrage landet zuerst hier. Die drei Modi — selbst signiert, Let's Encrypt, external — decken die drei Deployment-Formen ab, nach denen die meisten Operator greifen, und die Variable, die zwischen ihnen umschaltet, ist `TLS_MODE` in deiner `.env`. Die Env-Var-Referenz-Zeilen leben in [Umgebungsvariablen-Referenz](/de/self-hosted/configuration/environment-reference#tls). Diese Seite ist der per-Modus-Walkthrough und die Rezepte für Custom Domains und Bring-your-own-Zertifikate. ## Selbst signiert (Default) `TLS_MODE=selfsigned` lässt Caddy mit einem Zertifikat laufen, das es aus seiner internen CA generiert. Der Browser warnt beim ersten Mal, und der Host muss dem Cert vertrauen, um die Warnung zu unterdrücken — das ist für lokale Entwicklung gedacht: ```bash docker exec tale-proxy caddy trust ``` Das trust-Kommando importiert die CA von Caddy in den System-Trust-Store auf dem Host, der den Docker-Daemon laufen lässt. Andere Maschinen im Netzwerk sehen die Warnung weiter, ausser sie importieren die CA auch. Produktion nutzt diesen Modus nie. ## Let's Encrypt `TLS_MODE=letsencrypt` lässt Caddy ein echtes öffentliches Zertifikat ausstellen und erneuern. Drei Voraussetzungen müssen gelten, sonst scheitert die Ausstellungs-Schleife: - Der Hostname in `HOST` und `SITE_URL` löst zur öffentlichen IP des Hosts vom öffentlichen Internet auf. - Ports 80 und 443 sind vom öffentlichen Internet erreichbar (Port 80 trägt die ACME-HTTP-01-Challenge). - `TLS_EMAIL` ist auf ein Postfach gesetzt, das du liest — Let's Encrypt warnt dort vor Ablauf. ```bash # .env TLS_MODE=letsencrypt TLS_EMAIL=ops@yourdomain.com ``` Der erste Boot blockiert etwa eine Minute, während die ACME-Challenge läuft. Danach sind Erneuerungen automatisch 30 Tage vor Ablauf; Fehlschläge landen in `docker compose logs proxy`. ## Externer Proxy `TLS_MODE=external` lässt Caddy intern Klartext-HTTP servieren, und du stellst deinen eigenen Reverse-Proxy davor, der TLS upstream terminiert. Wähl das, wenn: - Du bereits ein CDN oder einen Load-Balancer betreibst, der Zertifikate handhabt. - Du TLS einmal am Rand deines VPCs terminieren und intern alles als Klartext laufen lassen willst. - Deine Compliance-Haltung eine bestimmte Zertifizierungsstelle verlangt, die Caddy nicht unterstützt. ```bash # .env TLS_MODE=external SITE_URL=https://tale.yourdomain.com # die URL, die deine Benutzer treffen ``` Der vorgelagerte Proxy braucht `X-Forwarded-Proto: https` auf jeder Anfrage, damit Tale korrekte Redirects und absolute URLs generiert. Ohne ihn landen Sign-in-Links auf `http://`, und das `Secure`-Flag des Auth-Cookies weist sie zurück. ## Custom Domain Die Domain selbst sind nur `HOST` und `SITE_URL`. Dasselbe Caddyfile in `tale-proxy` liest beide beim Boot. Änder sie, erstell den Proxy-Container neu (`docker compose up -d --force-recreate tale-proxy`), und die neue Domain ist innerhalb von Sekunden live. Let's Encrypt stellt für den neuen Namen bei der nächsten Anfrage, die den neuen Hostnamen trifft, neu aus. ```bash # .env HOST=tale.example.com SITE_URL=https://tale.example.com ``` Subpath-Deployments — Tale hinter `https://example.com/app/` — setzen zusätzlich `BASE_PATH=/app`. Der Reverse-Proxy upstream von Caddy strippt nichts; Tale handhabt das Präfix selbst. ## Bring-your-own-Zertifikat Für eine interne CA oder ein Wildcard-Cert, das du bereits besitzt, mountest du Cert und Schlüssel in `tale-proxy` und fügst eine `tls`-Direktive ins Caddyfile hinzu: ```yaml # compose.yml override services: proxy: volumes: - ./certs/fullchain.pem:/etc/tale/cert.pem:ro - ./certs/privkey.pem:/etc/tale/key.pem:ro environment: TLS_MODE: external # umgeht Caddys Auto-Ausstellung ``` Dann bau entweder ein `tale-proxy`-Image mit Custom-Caddyfile vor, oder stell deinen eigenen Reverse-Proxy vor Tale und bleib bei `TLS_MODE=external` — beide Pfade sind unterstützt, und der zweite ist einfacher. ## Wo das hingehört Die drei Modi decken die drei Deployment-Formen ab, die die meisten Teams treffen; die Env-Var-Zeilen leben in [Umgebungsvariablen-Referenz](/de/self-hosted/configuration/environment-reference#tls). Stellst du gerade einen frischen Produktions-Host auf, walkt [Produktions-Linux-Server-Install](/de/self-hosted/install/linux-server) Let's Encrypt End-to-End mit den Firewall- und DNS-Schritten in der richtigen Reihenfolge. # Umgebungsvariablen-Referenz Source: https://tale.dev/docs/de/self-hosted/configuration/environment-reference Tale liest seine Konfiguration aus einer einzigen `.env`-Datei im Repo-Stammverzeichnis. Etwa ein Dutzend Variablen sind beim ersten Boot Pflicht; der Rest stimmt das Verhalten ab. Diese Seite listet jede Variable, die [`.env.example`](https://github.com/tale-project/tale/blob/main/.env.example) mitbringt, was sie als Default hat und welche Oberfläche im Produkt sie konsumiert. Gruppen sind danach geordnet, wann du sie zuerst brauchst: Domain-Identität, TLS, Secrets, Datenbank, Instanz, Observability, Provider-Verschlüsselung. Ändert sich der Wert einer Variable, starte den Plattform-Container neu (`docker compose restart tale-platform tale-convex`), damit sie wirkt. ## Wie du diese Seite liest Jede Gruppe ist eine `Name | Default | Beschreibung`-Tabelle. Variablen, die als **Pflicht** markiert sind, müssen gesetzt sein, damit `docker compose up` erfolgreich ist. **Optionale** Variablen können unset bleiben; die Beschreibung benennt, was das Deaktivieren des Features bedeutet. Die `.env.example`-Datei bringt Inline-Kommentare mit, die jede Variable im Kontext erklären; diese Seite ist die strukturierte, gruppierte Referenz für dieselbe Menge. ## 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. | | `BASE_PATH` | unset | **Optional.** Pfad-Präfix für Subpath-Deployments hinter einem Reverse-Proxy (z. B. `/app`). Bei Root-Deployment unset lassen. | Die `SITE_URL` muss exakt mit dem übereinstimmen, was der Benutzer im Browser eingibt. Ein nachgestellter Slash, ein fehlender Port oder `http` statt `https` brechen den Auth-Callback und produzieren Sign-in-Schleifen. ## TLS | Name | Default | Beschreibung | | ----------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- | | `TLS_MODE` | `selfsigned` | Einer von `selfsigned`, `letsencrypt`, `external`. Siehe [TLS und Domains](/de/self-hosted/configuration/tls-and-domains). | | `TLS_EMAIL` | unset | Kontakt-E-Mail für Let's-Encrypt-Benachrichtigungen. Optional aber empfohlen in Produktion. | `selfsigned` lässt Caddy mit einem generierten Cert laufen — der Browser warnt, in Ordnung für Development. `letsencrypt` braucht eine echte Domain und Ports 80/443 vom öffentlichen Internet erreichbar. `external` lässt Caddy nur HTTP servieren; ein vorgelagerter Reverse-Proxy terminiert TLS. ## Sicherheits-Secrets (Pflicht) | Name | Default | Beschreibung | | ----------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BETTER_AUTH_SECRET` | Beispielwert in der Datei | **Pflicht.** Base64-Secret für den Better-Auth-Session-Signer. Generier mit `openssl rand -base64 32`. Rotieren invalidiert jede Session. | | `ENCRYPTION_SECRET_HEX` | Beispielwert in der Datei | **Pflicht.** 32-Byte-Hex-Schlüssel. AES-256-Schlüssel für OAuth- und Integrations-Credentials und HKDF-Input für die Guardrails-Secret-Box. Generier mit `openssl rand -hex 32`. Rotieren invalidiert jeden DB-Ciphertext; Operator müssen betroffene Secrets neu eingeben. | | `INSTANCE_SECRET` | Beispielwert in der Datei | **Pflicht.** Wird genutzt, um den Convex-Admin-Schlüssel für `tale deploy` abzuleiten. Deploy schlägt fehl, wenn unset. | Ersetze die Werte, die in `.env.example` mitkommen, bevor du die Instanz exponierst — sie sind absichtlich unsichere Platzhalter. ## Datenbank Tale betreibt zwei Postgres-Datenbanken: den operativen Speicher (`db`, Port 5432) hinter dem Convex-Backend und den Wissens-Korpus (`knowledge-db`, Port 5433), der Dokument-Chunks, Embeddings und gecrawlte Seiten hält. Beide sind ParadeDB und teilen sich `DB_PASSWORD`, aber sie sind unabhängig — zeig jede für sich auf externe Infrastruktur. | Name | Default | Beschreibung | | ------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DB_PASSWORD` | `tale_password_change_me` | **Pflicht.** Passwort für den selbst gehosteten Postgres-Benutzer. Vor der Produktion ändern. Von beiden Datenbank-Containern genutzt. | | `POSTGRES_URL` | aus `DB_PASSWORD` konstruiert | **Optional.** Überschreibt die automatisch konstruierte URL der operativen Datenbank. Nutze das, wenn du auf einen externen Postgres oder einen Nicht-Standard-Host/Port zeigst. | | `KNOWLEDGE_DATABASE_URL` | `postgresql://tale:${DB_PASSWORD}@knowledge-db:5432/tale_knowledge` | **Optional.** Verbindungs-URL, die das Convex-Backend für den Wissens-Korpus nutzt. Überschreib sie, um den Korpus auf dein eigenes verwaltetes ParadeDB zu verlagern — der datenresidenz-sensible Speicher wandert unabhängig. | | `KNOWLEDGE_DB_NAME` | `tale_knowledge` | **Optional.** Name der Wissensdatenbank. Der mitgelieferte `knowledge-db`-Container erstellt diese Datenbank beim ersten Boot. | Die auto-konstruierte operative Form ist `postgresql://tale:${DB_PASSWORD}@db:5432`. Convex erwartet diese URL ohne Datenbanknamen; der Name wird aus der Instanz-Konfiguration abgeleitet. Der Wissens-Korpus lebt in `tale_knowledge` mit den Schemata `private_knowledge` und `public_web`; die UI unter **Einstellungen > Datenresidenz** schreibt eine reichere Per-Store-Konfiguration als diese rohen Variablen, behandelt in [Datenresidenz](/de/self-hosted/configuration/data-residency). ## Observability | Name | Default | Beschreibung | | --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `SENTRY_DSN` | unset | Sentry-DSN für Error-Tracking. Unset zum Deaktivieren. Kompatibel mit selbst gehostetem GlitchTip und Bugsink. | | `SENTRY_TRACES_SAMPLE_RATE` | unset | Optionale Sample-Rate für Performance-Traces (`0.0`–`1.0`). Standard-Verhalten hängt vom Deployment ab. | | `METRICS_BEARER_TOKEN` | unset | Bearer-Token, das für den Zugriff auf die Prometheus-`/metrics/*`-Endpoints nötig ist. Unset hält Metrics-Endpoints von aussen unerreichbar. | `METRICS_BEARER_TOKEN` zu setzen exponiert zwei Endpoints hinter dem Token: `/metrics/platform` und `/metrics/convex` (Convex' 261 eingebaute Metriken, die jetzt auch die RAG- und Crawl-Timings tragen). Siehe [Observability-Konfig](/de/self-hosted/configuration/observability-config) für die Scrape-Konfiguration. ## Provider-Secrets-Verschlüsselung | Name | Default | Beschreibung | | ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SOPS_AGE_KEY` | unset | Inline-age-Secret-Key. Verschlüsselt `providers/*.secrets.json`. Standardmodus nach `tale init`. Mehrere Keys sind inline nicht unterstützt. | | `SOPS_AGE_KEY_FILE` | unset | Pfad zu einer Datei mit einem oder mehreren age-Keys (einer pro Zeile; `#`-Kommentare erlaubt). Pflicht für Key-Rotation. Schliesst sich mit der Inline-Form aus. | Wenn beide age-Vars unset sind, speichert Tale `providers/*.secrets.json` als Klartext-JSON mit Modus 0600. Erreich diesen Modus nur, wenn der Host-Storage at-rest verschlüsselt ist oder die Dateien von externem Tooling erzeugt werden (ein Kubernetes-Secret-Mount, ein Vault-Template). Einen age-Key zu rotieren bedeutet, den neuen Key anzuhängen, jeden Provider in der UI neu zu speichern, dann den alten Key zu entfernen. Siehe [Secrets mit SOPS](/de/self-hosted/configuration/secrets-with-sops) für den vollen Rotations-Walkthrough. Die Umgebungsvariablen-Schlüsselquelle braucht keinen Deployment-Schalter: ein Anbieter kann seinen Schlüssel aus einer Umgebungsvariable statt aus einer Secrets-Datei lesen, solange die Variable mit dem reservierten Präfix `TALE_PROVIDER_KEY_` benannt ist (jeder andere Name wird abgelehnt). Der Mechanismus — die Präfix-Schranke, Auflösungs-Reihenfolge, die 40-Zeichen-Grenze, die Neustart-Anforderung — ist in [Anbieter](/de/self-hosted/configuration/providers#environment-variable-key-source) dokumentiert. Eine [Token-Quelle](/de/platform/admin/token-sources) folgt demselben Muster für das Auth-Geheimnis, das sie _an den Broker_ sendet: Sie liest aus einem verschlüsselten `token-sources/<slug>.secrets.json`-Sidecar oder aus einer Umgebungsvariable, die mit dem reservierten Präfix `TALE_TOKEN_SOURCE_` benannt ist (jeder andere Name wird abgelehnt, sodass das Feld nie auf ein Deployment-Geheimnis zeigen kann). Die Variable gilt pro Quelle; definier sie hier oder in deinem Secret-Manager, damit sowohl die Plattform als auch das Convex-Backend sie lesen können. ## Feature-Flags Optionale Schalter für Features, die standardmässig nicht aktiviert sind. Jeder Flag schaltet ein Feature beim Boot ein oder aus; das Umschalten braucht einen Neustart des Plattform-Containers. | Name | Default | Beschreibung | | ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `TRUSTED_HEADERS_ENABLED` | `false` | Aktiviert den Trusted-Headers-Auth-Modus (Identität vom Reverse-Proxy geliefert). | | `FILE_EVENTS_ENABLED` | `false` | Aktiviert Datei-Watching-Events für die OneDrive-Sync-Integration. | | `TALE_DEPLOYMENT_CONFIG_ADMINS` | unset | Kommagetrennte E-Mail-Allowlist der Operatoren, die die Datenresidenz bearbeiten dürfen. Leer/nicht gesetzt = nur lesend für alle Admins. | ## RAG-Retrieval-Tuning Optionale Stellschrauben für die Wissensdatenbank-Suche. Der In-Process-RAG-Pfad (Convex-Node-Actions) bewertet Ergebnisse mit einem Cross-Encoder neu, wenn Re-Ranking an ist. Alle tragen das `RAG_`-Präfix und werden von den Containern `platform` und `convex` beim Boot gelesen; nach einer Änderung führe `docker compose restart platform convex` aus, damit sie wirkt. | Name | Default | Beschreibung | | ---------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `RAG_RERANKING_ENABLED` | `false` | Bewertet die zusammengeführten BM25- und Vektor-Kandidaten mit einem Cross-Encoder neu, bevor Ergebnisse zurückkommen. Mehr Präzision, mehr Latenz pro Query. | | `RAG_RERANKING_MODEL` | `cross-encoder/ms-marco-MiniLM-L-6-v2` | Cross-Encoder-Modellkennung, die an den Rerank-Provider übergeben wird. | | `RAG_RERANKING_PROVIDER` | `local` | Muss auf `api` gesetzt sein, um Re-Ranking zu aktivieren — es schickt die Kandidaten an einen externen `/rerank`-Endpoint (Cohere/Jina-kompatibel). `local` wird nicht mehr unterstützt und scheitert sofort. | | `RAG_RERANKING_TOP_K` | `10` | Maximale Anzahl Ergebnisse, die der Reranker zurückgibt. Die Antwort übersteigt nie das `top_k` der Anfrage. | | `RAG_RERANKING_CANDIDATES` | `30` | Grösse des Kandidaten-Pools für den Reranker. Ein breiterer Pool verbessert die Neubewertung und kostet proportional mehr Zeit pro Query. | | `RAG_RERANKING_API_BASE_URL` | unset | Basis-URL für den Rerank-Provider; die Plattform ruft `{base_url}/rerank` auf. Pflicht, wenn Re-Ranking aktiviert ist. | | `RAG_RERANKING_API_KEY` | unset | Bearer-Token für den externen Rerank-Endpoint. Unset lassen für unauthentifizierte Endpoints. | Re-Ranking ist standardmässig deaktiviert, weil es Latenz pro Query addiert und von einem externen Endpoint abhängt. Aktiviere es — indem du `RAG_RERANKING_PROVIDER=api` setzt und `RAG_RERANKING_API_BASE_URL` auf einen gehosteten Rerank-Service zeigst — wenn Retrieval-Präzision wichtiger ist als Antwortzeit. Es gibt kein In-Process-Modell zum Herunterladen oder Cachen; mit ausgeschaltetem Re-Ranking gibt die Suche das einfache zusammengeführte BM25-+-Vektor-Ranking zurück. ## 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. | Lass es unset, um die Standard-Sitzungsdauer zu behalten. Wenn gesetzt, läuft eine inaktive Sitzung serverseitig ab, sobald das Fenster verstrichen ist, während eine aktive sich bei jeder Anfrage weiter verschiebt. Org-Admins können das wirksame Fenster pro Organisation verkürzen — niemals über diese Obergrenze hinaus verlängern — über die [Governance-Richtlinie zur Sitzungs-Leerlaufzeit](/de/platform/admin/governance/policies-and-limits); inaktive Sitzungen unter dieser Richtlinie widerruft ein Lauf, der etwa alle fünf Minuten läuft. ## Wo das hingehört Die Variablen hier sind die Kontaktoberfläche des Operators; die UI-Oberfläche, die die meisten von ihnen konsumiert, lebt unter [Plattform-Verwaltung](/de/platform/admin/overview). Provider-Keys sind die eine Halb-und-Halb-Sache: die Keys selbst leben in `providers/*.secrets.json`, aber die UI unter **Einstellungen > KI-Anbieter** ist, wie du sie in der Praxis hinzufügst und rotierst. Die nächste Lektüre, die sich lohnt, ist [Anbieter](/de/self-hosted/configuration/providers) — sie behandelt die Datei-Form, die SOPS-Modi und das Resolve-und-Failover-Verhalten. # Authentifizierung Source: https://tale.dev/docs/de/self-hosted/configuration/authentication Tale bringt vier Sign-in-Modi mit, die ein Operator pro Instanz wählt. Der Default ist lokales Passwort, mit einem Benutzer pro E-Mail; Microsoft Entra und generisches OIDC delegieren die Identität an einen externen Anbieter; trusted Headers übergibt die Verantwortung an einen Reverse-Proxy, der SSO upstream bereits terminiert. Die Entscheidung ist insofern dauerhaft, als sie prägt, wie Benutzer provisioniert werden — Modi nach Rollout zu wechseln ist möglich, aber jeder bestehende Benutzer muss auf die neue Identitätsquelle umgemappt werden. Lokales Passwort und trusted Headers schalten Env-Vars um ([Umgebungsvariablen-Referenz](/de/self-hosted/configuration/environment-reference)); Microsoft Entra und generisches OIDC werden pro Organisation in der laufenden App konfiguriert. Diese Seite ist der Modus-für-Modus-Durchgang — wann du jeden wählst, was er für den Benutzer verändert, was bricht, wenn er fehlkonfiguriert ist. ## Lokales Passwort (Default) Lokales Passwort ist der Modus, den du bekommst, wenn du nichts setzt. Die Plattform speichert einen bcrypt-Hash in Postgres, signiert die Session mit `BETTER_AUTH_SECRET`, und der Benutzer meldet sich mit einer E-Mail und einem Passwort an, mit dem der Admin ihn eingeladen hat. Kein externer Identitäts-Anbieter ist beteiligt. Greif danach auf kleinen Instanzen und Air-gapped-Deployments, wo das Hinzufügen eines IdP mehr Reibung erzeugt als es löst. Der Preis: Passwort-Reset läuft über den Admin (oder über E-Mail, wenn `SMTP_*` konfiguriert ist), und es gibt keine SSO-Story. ```bash # .env — keine Flags für lokales Passwort nötig HOST=localhost SITE_URL=https://localhost BETTER_AUTH_SECRET=... ``` ## Microsoft Entra Der Microsoft-Entra-Modus fügt einen **Weiter mit SSO**-Button zum Sign-in-Bildschirm hinzu und nimmt Benutzer aus einem Tenant an, den du kontrollierst. Es gibt keinen Env-Var-Schalter: Die Verbindung wird pro Organisation unter **Einstellungen > Enterprise-SSO** konfiguriert, sobald die Plattform läuft — wähle das Protokoll **Microsoft Entra ID** und trage Client-ID, Client-Secret und Issuer-URL aus deiner App-Registrierung ein. Der vollständige Durchgang, inklusive Rollen-Mapping und Gruppen-zu-Teams-Sync, ist [Enterprise-SSO und Bereitstellung](/de/platform/admin/enterprise-sso). Zwei Deployment-Werte müssen stimmen, bevor der Flow funktionieren kann: `SITE_URL`, weil die Sign-in-Redirect-URL daraus abgeleitet wird, und `BETTER_AUTH_SECRET`, das den OAuth-State signiert. Der Redirect-URI, den du in Entra registrierst, ist `${SITE_URL}${BASE_PATH}/http_api/api/sso/callback` — die Einstellungsseite zeigt die exakte URL zum Kopieren, und sie muss Byte für Byte übereinstimmen, sonst lehnt Entra den Sign-in mit `AADSTS50011` ab. Die Tenant-ID in der Entra-App-Registrierung grenzt ein, wer sich anmelden kann; eine Multi-Tenant-Registrierung akzeptiert jeden mit einem Microsoft-Konto, was selten ist, was du willst. ## Generisches OIDC Generisches OIDC akzeptiert jeden spec-konformen Identitäts-Anbieter — Keycloak, Authentik, Okta, Google Workspace. Die Konfiguration lebt auf der **Single Sign-On**-Karte unter **Einstellungen > Integrationen**: Wähle den Anbietertyp **Generisches OIDC**, trag Aussteller-URL, Client-ID und Client-Secret ein, und Tale liest die Authorization-, Token- und Userinfo-Endpunkte aus dem `.well-known/openid-configuration`-Dokument des Ausstellers. Der Flow nutzt den Standard Authorization-Code-Grant mit PKCE (S256). Tale speichert kein Secret auf Platte für OIDC; Client-ID und Client-Secret liegen im verschlüsselten Credential-Store. Der Redirect-URI, den du bei deinem Anbieter registrierst, ist `${SITE_URL}/http_api/api/sso/callback`. Identitäts-Anbieter sind sich uneins, wo Claims liegen, also lässt dich die Karte auf deine zeigen. Die Felder **E-Mail-Claim**, **Namens-Claim** und **Gruppen-Claim** nehmen einen Claim-Namen oder einen Punktpfad in die Userinfo-Antwort — Keycloaks Realm-Rollen liegen zum Beispiel unter `realm_access.roles`. Rollenzuordnungsregeln weisen Plattformrollen beim Sign-in zu: Eine **Gruppe**-Regel matcht die Gruppen des Benutzers gegen ein Platzhalter-Muster (`platform-admin*` → Admin), eine **Claim**-Regel matcht einen beliebigen per Punktpfad aufgelösten Claim. **Teams automatisch bereitstellen** spiegelt die Gruppen, die dein Anbieter zurückgibt, bei jedem Sign-in als Tale-Teams — abzüglich der Gruppen, die du ausschließt. Ein durchgerechnetes Keycloak-Beispiel: Lege einen Confidential Client `tale-platform` mit dem Redirect-URI oben an, ergänze einen Group-Membership-Mapper, damit der Client `groups` in Userinfo ausgibt, setze dann in Tale den Aussteller auf `https://keycloak.example.com/realms/<realm>`, füge eine Gruppen-Regel `platform-admin*` → Admin hinzu und klicke **Verbindung testen** — das validiert die Discovery, bevor irgendetwas gespeichert wird. Das ist der Modus für Teams, die bereits einen IdP betreiben und ihre bestehende Identitäts-Oberfläche in Tale haben wollen. ## Trusted Headers Trusted Headers ist der Modus für Sites, die SSO an einem vorgelagerten Reverse-Proxy terminieren — oauth2-proxy, Pomerium, Authelia. Der Proxy authentifiziert den Benutzer und leitet identifizierende Header weiter (`X-Auth-Request-Email`, `X-Auth-Request-Preferred-Username`); Tale vertraut diesen Headern und legt den Benutzer-Datensatz on-the-fly an oder aktualisiert ihn. ```bash # .env TRUSTED_HEADERS_ENABLED=true ``` Das Bedrohungsmodell ist heikel. Alles, was den Plattform-Container mit diesen Headern erreichen kann, wird zum Benutzer, der in ihnen genannt ist. Beschränke den Plattform-Port so, dass nur der Proxy mit ihm sprechen kann (ein Docker-Netzwerk oder eine Host-Firewall-Regel), und exponier den Plattform-Container nie direkt zum Internet, wenn dieser Modus an ist. ## Wo das hingehört Die vier Modi sind im Geist gegenseitig ausschliessend, aber technisch additiv — Microsoft Entra und trusted Headers können auf derselben Instanz koexistieren, wenn deine IdP-Story mitten in der Migration steckt. Die volle per-Modus-Abwägungstabelle lebt in [Mitglieder und Rollen](/de/platform/admin/members-and-roles) auf der Benutzerseite; diese Seite deckt den Schalter des Operators ab. Die nächste Konfigurationsseite, die zu lesen sich lohnt, ist [Anbieter](/de/self-hosted/configuration/providers) — sobald Benutzer sich anmelden können, brauchst du immer noch mindestens einen Modell-Anbieter verdrahtet, bevor sie irgendetwas tun können. # Anbieter Source: https://tale.dev/docs/de/self-hosted/configuration/providers Tale speichert jeden Modell-Anbieter als zwei Dateien unter `providers/` — eine `<name>.json` für die öffentliche Form (Base-URL, Modelle, Capabilities) und eine `<name>.secrets.json` für die API-Schlüssel. Die Trennung existiert, damit die Config sicher zu committen ist und die Secrets die verschlüsselte Behandlung bekommen, die SOPS ihnen gibt. Der `tale-platform`-Container liest beide beim Boot und beobachtet sie auf Änderungen; den Container neu zu starten ist nicht nötig, um Edits aufzunehmen. Die Referenz ist das Dateiformat auf Platte und die Reihenfolge der Operationen, wenn du einen Anbieter hinzufügst. Der UI-gesteuerte Flow ("Einstellungen > Anbieter") sitzt auf denselben Dateien; beide erzeugen identische Resultate. ## Die Config-Datei `providers/<name>.json` beschreibt die öffentliche Form des Anbieters. Der `displayName` taucht in der UI auf, das `models`-Array nennt alles, was durch diesen Anbieter erreichbar ist, und jedes Modell deklariert seine Tags (`chat`, `vision`, `embedding`, `transcription`, `text-to-speech`). ```json { "displayName": "OpenRouter", "description": "Chat, Vision, Embeddings, Sprache und Bildgenerierung über einen Key.", "baseUrl": "https://openrouter.ai/api/v1", "secretsEnv": "TALE_PROVIDER_KEY_OPENROUTER", "defaults": { "transcription": "openai/whisper-1", "text-to-speech": "openai/gpt-4o-mini-tts-2025-12-15" }, "models": [ { "id": "openai/whisper-1", "displayName": "Whisper v1", "tags": ["transcription"], "transcriptionMode": "json-base64", "cost": { "centsPerAudioMinute": 0.6 } } ] } ``` Die vollständige Menge der Felder lebt in [`builtin-configs/providers/`](https://github.com/tale-project/tale/tree/main/builtin-configs/providers). Der ausgelieferte Default ist eine einzige `openrouter.json`, die Chat, Vision, Embeddings, Transkription, Text-to-Speech und Bildgenerierung abdeckt — ein Key für alles — mit kuratierten Presets für die gängigen Anbieter (Anthropic, OpenAI, Google, xAI, Mistral, Meta, DeepSeek, Qwen, Cohere, Amazon, Perplexity und mehr). Um einen Anbieter direkt statt über OpenRouter aufzurufen, füg eine weitere Datei hinzu (z. B. eine `openai.json`, die auf `https://api.openai.com/v1` zeigt); siehe [Modelle out of the box](/de/platform/models) für den vollen Default-Katalog. `transcriptionMode` wählt, wie der Request-Body eines `transcription`-Modells geformt wird: `json-base64` (OpenRouters `input_audio`-Envelope) oder, wenn weggelassen, `multipart` — der OpenAI/Whisper-`multipart/form-data`-Upload, den auch vLLM, LocalAI und ein direkter OpenAI-Key erwarten. Setz es passend zum Transkriptions-Endpunkt, auf den du zeigst. ### Modell-Capabilities und Auto-Sync Jedes Modell kann optionale Metadaten deklarieren, die das komplexitätsbasierte Routing und der Adaptive Reasoning Governor nutzen: `contextWindow`, `maxOutputTokens`, `qualityScore` (0–1), `tier` (`draft`/`standard`/`frontier`), `routingTags` (bevorzugte Domänen), `reasoning` (der Steuer-Knopf — `effort` oder `budgetTokens`) und `promptCaching` (`auto-server` oder `explicit-breakpoints`). Was du weglässt, wird zur Laufzeit aus dem OpenRouter-Katalog ergänzt; was du setzt, gewinnt. Setze `"hidden": true`, um ein Modell aus den Auswahllisten (Chat-Eingabe, Agenten-Erstellung) zu entfernen, es aber für Agents auflösbar zu halten, die es bereits referenzieren — so ziehst du eine abgelöste Version zurück, ohne bestehende Workflows zu brechen. Diese Felder bleiben auch von selbst aktuell: Einmal pro Woche führt Tale frische OpenRouter-Fakten in die Anbieter-Config jeder Organisation zusammen — fügt neuere Flaggschiff-Versionen hinzu, blendet abgelöste aus und aktualisiert Capability-Werte — und verändert dabei nur die Felder, die du nicht angepasst hast. Schalte das pro Organisation mit dem **Wöchentliche Auto-Synchronisierung**-Schalter auf der Modellkatalog-Karte unter **Einstellungen > Anbieter** aus. Wenn `maxOutputTokens` nicht gesetzt ist, begrenzt Tale die Ausgabe auf **32'768** Tokens. Setze `0`, um gar keine Begrenzung zu senden. Senke den Wert auf das tatsächliche Limit deines Deployments, falls der Anbieter zu grosse Werte ablehnt (z. B. ein Azure-GPT-4o-Deployment mit `max_tokens is too large`). ### Request-Body-Map Manche Endpunkte erwarten eine etwas andere Anfrageform als die übliche OpenAI-kompatible. Ein Modell — oder der Anbieter als Standard — kann eine `requestBodyMap` deklarieren, die den finalen Request-Body beim Versand umschreibt: ```json { "requestBodyMap": { "rename": { "max_tokens": "max_completion_tokens" }, "remove": ["frequency_penalty"] } } ``` `rename` benennt einen Feldnamen in einen anderen um (wird zuerst angewendet); `remove` entfernt Felder, die der Endpunkt ablehnt. Eine modell-spezifische `requestBodyMap` überschreibt die auf Anbieter-Ebene bei kollidierenden Schlüsseln. Anders als `providerOptions` erreichen diese Anweisungen den Anbieter nie — sie schreiben den Body direkt um und sind damit der unterstützte Weg, ein reserviertes Feld wie `max_tokens` zu ändern. Der klassische Fall ist ein OpenAI-/Azure-**Reasoning**-Deployment (o-Serie, GPT-5), das `max_tokens` ablehnt und `max_completion_tokens` verlangt. Wenn du das Modell als Reasoning-Modell kennzeichnest (den `reasoning`-Knopf setzt), wendet Tale genau diese Umbenennung automatisch an — `requestBodyMap` brauchst du dann nur noch für andere Endpunkt-Eigenheiten. ## Die Secrets-Datei `providers/<name>.secrets.json` ist ein flaches JSON-Objekt mit dem API-Schlüssel unter dem Feldnamen, den der Anbieter erwartet: ```json { "apiKey": "sk-..." } ``` Mit gesetztem `SOPS_AGE_KEY` oder `SOPS_AGE_KEY_FILE` wird diese Datei verschlüsselt auf Platte gespeichert. Mit beiden unset ist sie Klartext mit Dateimodus 0600 — erreich diesen Modus nur auf Platten, die at-rest verschlüsselt sind. Der vollständige Verschlüsselungs-Walkthrough lebt in [Secrets mit SOPS](/de/self-hosted/configuration/secrets-with-sops). ## Umgebungsvariable als Schlüsselquelle {#environment-variable-key-source} Liegen deine Secrets schon in Kubernetes Secrets, Vault oder einem Cloud-Secret-Manager, kannst du einen Anbieter auf eine **Umgebungsvariable** zeigen statt auf eine Secrets-Datei. Füg ein `secretsEnv` zur Config-Datei hinzu (es nennt die Variable; der Name selbst ist kein Secret und bleibt darum in der committbaren Config): ```json { "displayName": "OpenRouter", "baseUrl": "https://openrouter.ai/api/v1", "secretsEnv": "TALE_PROVIDER_KEY_OPENROUTER", "models": [ { "id": "openai/gpt-4o", "displayName": "GPT-4o", "tags": ["chat", "vision"], "secretsEnv": "TALE_PROVIDER_KEY_OPENAI_DIRECT" } ] } ``` Zwei Leitplanken gelten: - **Reserviertes Präfix (Pflicht).** Der Variablenname muss mit `TALE_PROVIDER_KEY_` beginnen (z. B. `TALE_PROVIDER_KEY_OPENROUTER`). Jeder andere Name wird abgelehnt, sodass eine Config, die eine Variable ohne Präfix nennt, zu keinem Schlüssel auflöst. Das hindert einen Config-Schreib-Akteur daran, `secretsEnv` auf ein fremdes Deployment-Secret (z. B. `SOPS_AGE_KEY`) zu zeigen und es an eine Anbieter-URL senden zu lassen. Die Präfix-Schranke ist fest verdrahtet — es gibt keinen Deployment-Schalter. - **Länge.** Der Name muss 40 Zeichen oder kürzer sein — die Plattform synct Umgebungsvariablen zu ihrem Convex-Backend, das Variablennamen bei 40 kappt. Auflösungs-Reihenfolge, höchste zuerst: modell-level `secretsEnv` → anbieter-level `secretsEnv` → die Secrets-Datei (`modelKeys[id]`, dann `apiKey`). Jede Stufe wird übersprungen, wenn sie nichts liefert, sodass eine konfigurierte-aber-leere Variable auf die Datei zurückfällt. Env-Werte werden getrimmt (ein nachgestellter Zeilenumbruch aus einem gemounteten Secret ist eine häufige Ursache für `401`s). Anders als die Secrets-**Datei** — die der Watcher bei jeder Anfrage neu liest — wird ein Umgebungsvariablen-**Wert** einmal beim Prozessstart gelesen. Ihn zu ändern verlangt einen **Neustart des `tale-platform`-Containers** (er synct Env beim Boot neu zu Convex). Die Plattform synct die Variable automatisch zum Convex-Backend, also nehmen die In-Process-RAG- und Crawler-Actions sie aus demselben Sync auf — es gibt keinen separaten Service neu zu erstellen. ## Einen Anbieter hinzufügen Die Reihenfolge ist wichtig — der Watcher liest die Config-Datei zuerst, um zu wissen, dass der Anbieter existiert, und löst dann das Secret bei der ersten Anfrage auf. 1. Leg die Config-Datei bei `providers/<name>.json` ab. 2. Leg die Secrets-Datei bei `providers/<name>.secrets.json` ab (verschlüsselt oder Klartext, je nach deinem SOPS-Modus). 3. Aktualisiere **Einstellungen > Anbieter** in der UI — der neue Anbieter erscheint innerhalb weniger Sekunden (der Watcher pollt alle 2 s). 4. Wähle das Default-Modell des neuen Anbieters unter **Einstellungen > Modelle**, damit Agents, die "default" auflösen, dort landen. Ist die Config-Datei fehlerhaft, loggt die Plattform eine Warnung und überspringt den Anbieter; der Rest bleibt erreichbar. ## Einen Schlüssel austauschen Editier die Secrets-Datei in-place — der Watcher nimmt die Änderung auf, und die nächste Anfrage an diesen Anbieter nutzt den neuen Schlüssel. Bestehende in-flight-Anfragen halten noch den alten Schlüssel; abbrechen und neu versuchen, um die Re-Auflösung zu erzwingen. (Schlüssel, die aus einer [Umgebungsvariable](#environment-variable-key-source) stammen, sind die Ausnahme: den Wert zu ändern verlangt einen Container-Neustart, nicht nur einen Datei-Edit.) ## Einen Anbieter deaktivieren Entweder lösch beide Dateien, oder setze `"disabled": true` an der obersten Ebene der Config. Das Deaktivieren hält die Datei für später auf Platte (praktisch, wenn du die Modell-Liste behalten willst, aber das Billing stoppen); das Löschen entfernt sie ganz. Agents, die den Anbieter explizit genannt haben, fangen an, bei der nächsten Anfrage zu scheitern — schalt sie vorher auf einen Fallback um. ## Wo das hingehört Anbieter sind das eine Halb-und-Halb zwischen Server-Config (dieser Seite) und UI (dem **Anbieter**-Bildschirm). Die Schlüssel selbst leben in `providers/*.secrets.json`; das SOPS-Handling lebt in [Secrets mit SOPS](/de/self-hosted/configuration/secrets-with-sops). Die Modell-Level-Defaults, gegen die Agents auflösen, sind unter [Plattform > Modelle](/de/platform/models) dokumentiert. # Retention Source: https://tale.dev/docs/de/self-hosted/configuration/retention Retention in Tale ist die Policy, die alte Daten nach einem Zeitplan löscht — Chats, Dokumente, Audit-Logs, Workflow-Ausführungen, Token-Nutzungs-Ledger-Zeilen. Der Operator setzt Grenzen (Minimum und Maximum) pro Kategorie; der Admin jeder Organisation wählt das tatsächliche Retention-Fenster innerhalb dieser Grenzen über **Einstellungen > Governance > Retention-Policy**. Die Trennung existiert, damit ein Hosting-Team Compliance-Untergrenzen durchsetzen kann, ohne jede Mandantin im Detail zu mikromanagen. Diese Seite deckt die Operator-Oberfläche ab. Die Admin-seitigen Controls und die per-Kategorie-Beschreibungen leben in [Governance > Retention-Policy](/de/platform/admin/governance/policies-and-limits). ## Wie die Grenzen funktionieren Jede Retention-Kategorie — Chat-Threads, Dokumente, Kunden, Lieferanten, Prompt-Templates, Ledger-Zeilen, Audit-Logs, Workflow-Ausführungen, Workflow-Trigger-Logs, Login-Versuche — hat ein `min` und ein `max`. Ein Org-Admin setzt einen Wert innerhalb dieses Fensters. Den Boden über eine bestehende Instanz hinweg anzuziehen ist ein mehrstufiger Flow: Operator schlägt die neue Grenze vor, jeder betroffene Admin sieht ein Banner, die Änderung greift, sobald sie akzeptiert ist. | Kategorie | Typische Untergrenze | Warum | | ------------------------- | -------------------- | ----------------------------------------------- | | Chat-Verlauf | 30 T | Die meisten wollen jüngsten Kontext, nicht ewig | | Dokumente | 1 J | Wissen veraltet langsam | | Audit-Logs | 1 J Minimum | Compliance-Frameworks erwarten ein Jahr | | Token-Nutzungs-Ledger | 90 T | Analytics und Budget-Berichte hängen an Zeilen | | Workflow-Ausführungs-Logs | 30 T | Debugging reicht selten weiter zurück | | Login-Versuche | 30 T | Brute-Force-Untersuchung braucht die Audit-Spur | Die mitgelieferten Defaults sind locker; zieh sie an, je nach deiner Compliance-Haltung. ## Wo du Grenzen setzt Unter dem Org-first-Layout sind Retention-Grenzen **pro Org**: editiere `retention.json` direkt im Unterbaum einer Org unter `TALE_CONFIG_DIR` (default `/app/data/` im Plattform-Container, also liegt die Datei unter `/app/data/<org>/retention.json`, z. B. `/app/data/default/retention.json`). Jede Org hat ihre eigene Datei; die `default`-Datei ist die Vorlage, die eine neue Installation beim ersten Start aufgreift. ```json { "chatHistory": { "min": 30, "max": 730, "unit": "days" }, "documents": { "min": 1, "max": 3650, "unit": "days" }, "auditLog": { "min": 365, "max": 3650, "unit": "days" }, "tokenLedger": { "min": 90, "max": 1095, "unit": "days" } } ``` Der Plattform-Container beobachtet die Datei; Änderungen schlagen ein Grenzen-Update für jede bestehende Org vor. Admins sehen den Vorschlag in ihrem **Retention-Policy**-Bildschirm und wenden ihn selbst an. Der Vorschlagen-dann-anwenden-Schritt ist Absicht: Eine Untergrenze anzuziehen kürzt Historie, was eine destruktive Aktion ist, die kein Operator stillschweigend bei jeder Mandantin landen sollte. Die vom Admin gewählten Aufbewahrungsfenster liegen in einer separaten Datei, `retention-policy.json`, neben den Grenzen im selben `governance/`-Ordner. Sie enthält flache Felder `<Kategorie>Enabled` / `<Kategorie>RetentionDays` (z. B. `"auditLogEnabled": true, "auditLogRetentionDays": 730`), nicht die `min`/`max`-Grenzen. Diese Datei schreibt **Einstellungen > Governance > Retention-Policy** in der App, Admins bearbeiten sie also normalerweise nie von Hand — halte sie getrennt von der vom Operator verwalteten Grenzen-Datei. ## Der Retention-Sweep Ein geplanter Cron in `tale-convex` läuft die tatsächliche Löschung. Jede Kategorie wird unabhängig gesweept — ein langsamer Lauf einer blockiert die anderen nicht. Löschungen sind audited (jede Kategorie hat ihr eigenes `*.retention_deleted`-Event), und eine Entität in ihrem Gnaden-Fenster wiederherzustellen ist von **Papierkorb** möglich, bevor der finale Sweep läuft. Audit-Log-Einträge unterliegen selbst der Retention, aber ihre Untergrenze wird pro Deployment durchgesetzt, nicht pro Org: Die strengste (kürzeste) Audit-Log-Retention über alle Orgs ist das, was tatsächlich läuft. Eine strengere Mandantin zieht alle enger — denk daran auf Multi-Tenant-Instanzen. ## Legal Hold Ein Legal Hold friert die Retention für einen bestimmten Scope ein: einen einzelnen Thread, einen Kunden-Datensatz oder eine ganze Organisation. Gehaltene Entitäten überspringen den Sweep, bis der Hold gelöst wird. Der Hold selbst ist audited; org-weite Holds sind laut genug, dass die UI eine Bestätigung anzeigt, bevor sie greifen. ## Wo das hingehört Die Grenzen-Datei ist der Hebel des Operators; die per-Kategorie-Fenster, die der Admin sieht, sind in [Retention-Policy](/de/platform/admin/governance/policies-and-limits) dokumentiert. Setzt du Grenzen gegen ein Compliance-Framework (DSGVO, HIPAA, SOC 2), ist die Audit-Log-Untergrenze meist das, was Auditoren zuerst prüfen. # Observability-Konfiguration Source: https://tale.dev/docs/de/self-hosted/configuration/observability-config Tale bringt drei Observability-Nähte mit: stdout-Logs aus jedem Container, Metriken im Prometheus-Format hinter einem Bearer-Token und optionales Sentry-Error-Reporting. Die Defaults sind laut genug, um einen Crash zu sehen, und leise genug, um in das journald eines einzelnen Hosts zu passen; die Produktions-Knöpfe unten fügen die strukturierten Pfade hinzu, die dein bestehender Monitoring-Stack scrapen kann. Keine der drei schickt etwas vom Host weg, ausser du konfigurierst sie dazu. Diese Seite deckt die serverseitigen Schalter ab. Das operatorseitige Alert-Playbook lebt in [Operations](/de/self-hosted/operate/observability/operations), und das symptomorientierte Nachschlagen in [Troubleshooting](/de/self-hosted/operate/observability/troubleshooting). ## Logs Jeder Container schreibt strukturierte JSON- oder Console-Logs nach stdout, vom Default-Driver `json-file` von Docker mit einer Rotation von 10 MB pro Datei und drei Dateien aufgefangen. Das Log-Ziel ist eine Funktion davon, wie du deployest: - Einzelner Host mit journald — `journalctl -u docker` trägt alles. - Einzelner Host ohne journald — `docker compose logs -f <service>` für live tailing. - Aggregator (Loki, Vector, Fluent Bit) — richte den Docker-Logging-Driver über `daemon.json` dorthin. Tale bringt keinen Log-Shipper mit. Der Driver-Tausch ist der unterstützte Integrations-Punkt. ## Metriken Der Caddy-Proxy exponiert drei Metric-Pfade, gegated von einem einzigen Bearer-Token: | Pfad | Quelle | Was drinsteckt | | -------------------- | --------------- | ----------------------------------------------------------------------------- | | `/metrics/platform` | `tale-platform` | HTTP-Latenz, Route-Counter, Node-Prozessmetriken, Antwortzeit-SLA-Ziel-Gauges | | `/metrics/convex` | `tale-convex` | 261 eingebaute Convex-Metriken, plus die RAG- und Crawl-Timings | | `/metrics/sla-rules` | `tale-platform` | Generierte Prometheus-Recording- + Alerting-Rules für die Antwortzeit-SLAs | Wissens-Arbeit (RAG-Suche, Dokument-Ingestion, Web-Crawling) läuft jetzt im Convex-Backend, also reiten ihre Timings auf der `/metrics/convex`-Reihe statt auf einem separaten Endpoint. Setze `METRICS_BEARER_TOKEN` in `.env`, um diese Endpoints zu aktivieren; lass es unset, damit sie jeder Anfrage 401 zurückgeben. Der `/metrics/sla-rules`-Pfad ist eine schreibgeschützte YAML-Rules-Datei, die du in Prometheus lädst, kein Scrape-Target — die Schwellen darin sind in [Operations](/de/self-hosted/operate/observability/operations) dokumentiert. Alles ausser den gelisteten Pfaden gibt ebenfalls 401 zurück, damit ein fehlgerouteter Scraper die internen Health-Endpoints der Plattform nicht versehentlich sieht. Eine funktionierende Prometheus-Scrape-Stanza: ```yaml scrape_configs: - job_name: tale-platform scheme: https metrics_path: /metrics/platform authorization: credentials: <METRICS_BEARER_TOKEN> static_configs: - targets: ['tale.example.com'] ``` Dupliziere die Stanza pro Pfad, oder nutze einen einzelnen Job mit `relabel_configs`, wenn du das bevorzugst. ## Error-Tracking mit Sentry Sentry ist opt-in über `SENTRY_DSN`. Selbst gehostete GlitchTip und Bugsink funktionieren auch, da sie dasselbe DSN-Format sprechen. Die Plattform- und die Convex-Container lesen beide den DSN und taggen Events mit dem Container-Namen. ```bash # .env SENTRY_DSN=https://your-key@your-sentry-host/project-id SENTRY_TRACES_SAMPLE_RATE=0.1 ``` Die Sample-Rate begrenzt Performance-Traces; lass sie unset für den Default 1.0 in Development und ziehe sie an (0.05–0.2) in Produktion. Stack-Frames werden unredigiert geschickt, also richte den DSN auf Infrastruktur, die du kontrollierst, wenn deine Error-Payloads sensibel sind. ## Was noch nicht mitkommt OpenTelemetry-Traces sind nicht in die Container eingebaut. Die Daten sind indirekt erreichbar — Convex-Action-Dauern und HTTP-Route-Timings kommen durch die Prometheus-Metriken — aber es gibt heute keinen OTLP-Exporter auf der Box. Brauchst du vollen Trace-Export, betreib einen OpenTelemetry Collector neben Tale und scrape die Prometheus-Endpoints aus ihm. ## Wo das hingehört Die drei Nähte oben sind die Kontaktpunkte mit dem Rest deines Monitoring-Stacks; die Alert-Schwellen und die Oncall-Checkliste leben in [Operations](/de/self-hosted/operate/observability/operations). Brennt etwas gerade und du brauchst den symptomorientierten Index, spring zu [Troubleshooting](/de/self-hosted/operate/observability/troubleshooting). # Secrets mit SOPS Source: https://tale.dev/docs/de/self-hosted/configuration/secrets-with-sops Tale speichert Anbieter-API-Schlüssel in `providers/*.secrets.json`-Dateien auf Platte. Der Default-Modus nach `tale init` verschlüsselt diese Dateien mit SOPS unter Verwendung eines age-Schlüssels; ein alternativer Modus liest mehrere Schlüssel aus einer Datei (der Rotations-Pfad); ein dritter Modus hält die Dateien als Klartext mit Dateimodus 0600 für Umgebungen, in denen die Platte at-rest verschlüsselt ist und die Rotation extern gehandhabt wird. Diese Seite ist der Operator-Durchgang durch die drei Modi und den sicheren Rotations-Pfad. Die Env-Vars, die die Modi steuern, sind `SOPS_AGE_KEY` und `SOPS_AGE_KEY_FILE` — ihre Referenz-Zeilen leben in [Umgebungsvariablen-Referenz](/de/self-hosted/configuration/environment-reference#provider-secrets-encryption). Diese Seite ist die längere Geschichte. ## Die drei Modi | Modus | Env-Vars | Wann nutzen | | -------------------- | ---------------------------------- | ------------------------------------------------------------------------ | | Inline age-Schlüssel | `SOPS_AGE_KEY=AGE-SECRET-KEY-1...` | Default nach `tale init`. Einzelner Host, einzelner Schlüssel. | | Schlüssel-Datei | `SOPS_AGE_KEY_FILE=/path/to/keys` | Pflicht für Rotation. Ein age-Schlüssel pro Zeile, `#`-Kommentare. | | Klartext bei 0600 | Beide unset | Platte at-rest verschlüsselt, oder externe Tooling schreibt die Dateien. | Der Plattform-Container wählt den Modus beim Boot. Die Inline-Form ist die einfachste; die Datei-Form ist die einzige, die mehrere Leser unterstützt (was Rotation ohne Downtime möglich macht); die Klartext-Form überspringt SOPS ganz und vertraut dem Dateisystem. ## Verschlüsselter Modus beim ersten Boot `tale init` generiert ein age-Schlüsselpaar und schreibt die private Hälfte in `SOPS_AGE_KEY` in deiner `.env`. Anbieter-Secret-Dateien, die durch **Einstellungen > Anbieter** geschrieben werden, werden beim Speichern verschlüsselt: ```bash # Inspizieren — die Datei ist SOPS-verschlüsseltes JSON, nicht der Klartext-API-Schlüssel cat providers/openai.secrets.json # { # "apiKey": "ENC[AES256_GCM,data:...,iv:...,tag:...]", # "sops": { ... } # } ``` Entschlüsselung passiert in-process, wenn der Plattform-Container die Datei liest. Der age-Schlüssel verlässt den Speicher des Plattform-Containers nie. ## Den age-Schlüssel rotieren Rotation ist der eine Pfad, den die Inline-Form nicht abdeckt — nur `SOPS_AGE_KEY_FILE` erlaubt dir, Ciphertext anzunehmen, der sowohl mit dem alten als auch dem neuen Schlüssel während des Umschaltens lesbar ist. Der Walk: ```bash # 1. Generiere einen neuen age-Schlüssel age-keygen -o /etc/tale/age-keys.txt # 2. Häng den neuen Schlüssel als zweite Zeile in der Datei an echo "AGE-SECRET-KEY-1NEW..." >> /etc/tale/age-keys.txt # 3. Richte .env auf die Datei und starte den Plattform-Container neu sed -i 's|^SOPS_AGE_KEY=.*|# SOPS_AGE_KEY=|' .env sed -i 's|^# SOPS_AGE_KEY_FILE=.*|SOPS_AGE_KEY_FILE=/etc/tale/age-keys.txt|' .env docker compose restart tale-platform tale-convex ``` Jetzt können sowohl der alte als auch der neue Schlüssel bestehende Dateien entschlüsseln. Speichere den API-Schlüssel jedes Anbieters unter **Einstellungen > Anbieter** neu — jedes Speichern erzeugt Ciphertext, der von beiden Schlüsseln lesbar ist. Sobald jeder Anbieter neu gespeichert wurde (die Spalte **Zuletzt rotiert** in der Anbieter-Tabelle sagt dir, welche noch alten Ciphertext halten), entferne den alten Schlüssel aus der Datei: ```bash # 4. Lass die alte Schlüssel-Zeile fallen und starte erneut neu sed -i '/^AGE-SECRET-KEY-1OLD/d' /etc/tale/age-keys.txt docker compose restart tale-platform tale-convex ``` Die Reihenfolge ist tragend: Entfern den alten Schlüssel nie, bevor jede Datei neu verschlüsselt ist, oder der Plattform-Container scheitert beim Lesen der noch-alten Dateien bei der nächsten Entschlüsselung. ## Auf Klartext umsteigen Wenn die Host-Platte at-rest verschlüsselt ist (LUKS, AWS-EBS-Verschlüsselung, GCP CSEK) und du keine zweite Schicht Schlüssel-Verwaltung willst, ist der Klartext-Modus die unterstützte Option. Kommentier sowohl `SOPS_AGE_KEY` als auch `SOPS_AGE_KEY_FILE` aus, starte neu und speichere jeden Anbieter neu — die Dateien sind jetzt JSON mit Modus 0600. Das Risikomodell verschiebt sich: Ein durchgesickerter Dateisystem-Dump ist jetzt ein durchgesickertes Credential-Dump. Wähl diesen Modus nur, wenn die Platten-Verschlüsselung echt ist (kein Häkchen), und auditiere die Backup-Story des Hosts, um zu bestätigen, dass kein Klartext-Snapshot entweicht. ## Externe Secret-Stores Wenn deine Schlüssel schon in Vault, einem Cloud-Secret-Manager oder Kubernetes Secrets liegen, ist die Umgebungsvariablen-Schlüsselquelle das erstklassige Pattern: zeig jeden Anbieter mit `secretsEnv` auf eine **Umgebungsvariable** und lass deinen Secret-Store diese Variable befüllen. Keine Klartext-Datei landet auf der Platte, und die Präfix-Schranke hindert einen Config-Schreib-Akteur daran, ein fremdes Deployment-Secret zu lesen. Der vollständige Mechanismus — die `TALE_PROVIDER_KEY_`-Präfix-Schranke, die Auflösungs-Reihenfolge und das Neustart-bei-Änderung-Verhalten — lebt in [Anbieter](/de/self-hosted/configuration/providers#environment-variable-key-source). Der Datei-Mount-Ansatz ist die Legacy-Alternative: Schreib die Klartext-`*.secrets.json`-Dateien aus dem externen Store und betreib Tale im Klartext-Modus. Das funktioniert weiterhin, legt aber den Klartext-Schlüssel auf die Platte und bricht, wenn du einen Anbieter über die UI speicherst — die UI überschreibt den Mount. Bevorzuge die Umgebungsvariablen-Quelle, sofern dich kein Zwang zur Datei-Form drängt. ## Wo das hingehört Diese Seite ist die vollständige Operator-Anleitung zur SOPS-Schicht; die Env-Var-Referenz-Zeilen sind in [Umgebungsvariablen-Referenz](/de/self-hosted/configuration/environment-reference#provider-secrets-encryption), und das Anbieter-Dateiformat selbst in [Anbieter](/de/self-hosted/configuration/providers). Ist ein Schlüssel durchgesickert, ist die Rotation derselbe Walk oben, dringend ausgeführt. # Selbst gehosteter Quickstart Source: https://tale.dev/docs/de/self-hosted/install/quickstart Das ist der schnellste Weg zu einem laufenden Tale: installiere die `tale`-CLI, dann zwei Befehle. Das Ergebnis ist deine eigene Org auf deiner eigenen Maschine, erreichbar im Browser. Gedacht ist das für einen Laptop oder einen einzelnen Host, auf dem du Tale ausprobieren willst; sobald du es ernsthaft betreiben willst, deckt die [Linux-Server-Strecke](/de/self-hosted/install/linux-server) eine gehärtete Produktions-Installation ab. ## Bevor du beginnst Du brauchst nichts zum Starten und eine Sache, bevor ein Agent antworten kann: - **Docker** — aber die CLI stellt es für dich bereit: Fehlt Docker, bietet `tale dev` an, es zu installieren oder zu starten, bevor irgendetwas anderes passiert. Läuft bei dir bereits [Docker Desktop](https://www.docker.com/products/docker-desktop) (v24+) oder Docker Engine plus Compose-Plugin unter Linux, nutzt die CLI das. - Einen **[OpenRouter-API-Schlüssel](https://openrouter.ai)** (oder einen beliebigen OpenAI-kompatiblen Anbieter), damit Agents ein Modell zum Reden haben. Für `tale init` brauchst du ihn nicht — du fügst ihn nach der Registrierung in der App hinzu, im Setup-Assistenten oder unter **Einstellungen > KI-Anbieter**, und du kannst später jeden Anbieter einwechseln. ## Von null bis angemeldet <Steps> <Step title="Installiere die CLI"> Der Installer erkennt dein OS, legt das `tale`-Binary auf deinen `PATH` und ist der einzige Schritt, der dein System anfasst — er fragt nach `sudo`, wenn das Installationsverzeichnis (Standard `/usr/local/bin`) nicht beschreibbar ist. <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> <Check> Gibt `tale --version` eine Versionsnummer aus, ist das Binary auf deinem `PATH` gelandet. </Check> </Step> <Step title="Erstelle ein Projekt"> ```bash tale init my-project cd my-project ``` `tale init` legt ein Projektverzeichnis an, generiert jedes Security-Secret und schreibt die `.env`, sodass es nichts von Hand zu editieren gibt. Die Defaults sind localhost und ein selbstsigniertes Zertifikat; die Produktions-Domäne wählst du später, bei `tale deploy`. Die eine Frage, die es stellt, ist, ob Agents in ihren Sandboxes `docker` / `docker compose` ausführen dürfen — der Default ist Nein, denn die Freigabe startet einen privilegierten inneren Docker; auf einer Einzelnutzer-Maschine kannst du zustimmen, als Multi-Tenant-Betreiber installierst du stattdessen Sysbox. Nach einem API-Schlüssel fragt es nicht; den sammelt die App ein, sobald du dich anmeldest. Es legt außerdem Beispiel-Agents, -Workflows, -Integrationen, -Provider, -Skills und -Branding unter `default/` ab und schreibt `AGENTS.md` (plus einen `CLAUDE.md`-Verweis), damit ein KI-Editor Konfigurationen mit voller Schema-Kenntnis bauen kann. Das meiste davon ist ein Katalog, keine aktive Konfiguration: Auf einer neuen Organisation sind nur Einträge mit `autoInstall` aktiv — den Unterschied erklärt die generierte `default/README.md`. </Step> <Step title="Starte Tale"> ```bash tale dev ``` Fehlt Docker, bietet `tale dev` zuerst an, es zu installieren oder zu starten. Der erste Lauf zieht dann mehrere Gigabyte an Images und baut den Container-Graph — die CLI zeigt den Pull-Fortschritt pro Image an und wartet weiter; in einem langsamen Netz kann das Dutzende Minuten dauern. Sobald der Stack bereit meldet (`Tale is running — open https://localhost`), öffnet `tale dev` automatisch deinen Browser. Kann es das nicht, gibt es die URL zum Besuchen aus. <Note> Dein Browser zeigt eine Zertifikatswarnung für das lokale selbstsignierte Zertifikat. Das ist erwartet — akzeptier sie, um fortzufahren. </Note> Deine Konfiguration unter `default/` wird in die laufende Instanz gemountet, sodass Änderungen an Agents, Workflows und Integrationen live nachladen. Stopp den Stack mit `Ctrl-C` (oder `tale dev --detach`, um ihn im Hintergrund laufen zu lassen). </Step> <Step title="Erstelle dein Konto"> Auf einer leeren Instanz gibt es keine Sign-up-Seite zu suchen: Der erste Besuch landet im einmaligen Setup-Wizard, der dein Konto anlegt, dich anmeldet, dich zum **Inhaber** macht und deine **Organisation** benennt. Du landest im Dashboard — ohne Admin-Key, und danach gibt es nichts abzuriegeln, denn alle nach dir kommen per Einladung dazu. <Note> [Erster Admin](/de/self-hosted/install/first-admin) behandelt den Wizard im Detail, wie Teammitglieder dazukommen und den Convex-Dashboard-Admin-Key — ein Backend-Inspektionswerkzeug, das mit der Anmeldung nichts zu tun hat. </Note> </Step> <Step title="Verbinde ein Modell und veröffentliche einen Agent"> Du hast jetzt eine leere Org. Zwei Handgriffe bringen dich zu etwas Nützlichem: Füg deinen OpenRouter-Schlüssel hinzu — der Setup-Assistent fragt direkt nach der Erstellung des Inhaber-Kontos danach, und **Einstellungen > KI-Anbieter** nimmt ihn jederzeit später an — und veröffentliche dann deinen ersten Agent mit [Einen Agent erstellen](/de/platform/agents/create). Eine Bestätigung auf der Anbieterzeile heißt, dass der Schlüssel funktioniert. <Check> Ein neuer Chat, der eine Nachricht beantwortet, ist der Beweis von Anfang bis Ende: Anbieter, Modell und Agent funktionieren. Von hier aus sind die [Plattform](/de/platform)-Docs die kanonische Referenz für jedes Feature, identisch zu Cloud. </Check> </Step> </Steps> ## Lieber pures Docker Compose? Die CLI umhüllt `docker compose`, damit du das nicht musst. Willst du den Stack lieber aus einem Klon des Repositorys fahren und Compose selbst verwalten — für Transparenz, Air-gapped-Builds oder deine eigene Automation — klon das Repo, kopier `.env.example` nach `.env`, setz `HOST` und `SITE_URL`, generier die Secrets und starte `docker compose up -d`. Die [Linux-Server-Strecke](/de/self-hosted/install/linux-server) und die [Docker-Compose-Referenz](/de/self-hosted/install/docker-compose-reference) decken diesen Weg von Anfang bis Ende ab. ## Fehlersuche - **`tale` nach der Installation nicht gefunden.** Der Installer benennt das Zielverzeichnis in seiner Ausgabe; stell sicher, dass dieses Verzeichnis auf deinem `PATH` liegt (unter Linux ist es meist `/usr/local/bin`). - **`tale dev` beendet mit einem Port-Konflikt.** Lies aus dem Compose-Fehler ab, welcher Port belegt ist. Ist es 443, bindet ein anderer Dienst HTTPS auf dem Host — gib ihn frei oder leg Tale mit `tale dev --port 8443` auf einen anderen Port (das Flag betrifft nur den HTTPS-Port). Der Sandbox-Spawner bindet immer `127.0.0.1:8003` und lässt sich nicht verlegen; deshalb können zwei Tale-Dev-Projekte nicht gleichzeitig auf einer Maschine laufen. - **Docker läuft nicht.** `tale dev` bietet an, es zu starten (oder zu installieren) — nimm die Rückfrage an, oder starte Docker Desktop selbst (`sudo systemctl start docker` unter Linux) und versuch es erneut. - **Ein Container crash-loopt beim ersten Boot.** Fast immer ein fehlendes Secret — lauf `tale dev` erneut, was das Environment-Setup erneut ausführt, oder inspizier die Logs mit `tale logs platform`. ## Wo das eingesetzt wird Du hast jetzt eine funktionierende Tale-Instanz auf deiner Maschine. Um sie ernsthaft zu betreiben, deckt die [Linux-Server-Strecke](/de/self-hosted/install/linux-server) TLS, Firewall, einen Non-root-Benutzer und die operativen Haken ab, die du vor echtem Traffic willst; [Die tale-CLI installieren](/de/self-hosted/install/cli-install) richtet die CLI so ein, dass du eine entfernte Instanz von deiner Workstation aus deployst und aktualisierst. # Installation Source: https://tale.dev/docs/de/self-hosted/install Tale zu installieren hat drei Formen, und die richtige hängt davon ab, was du mit dem Ergebnis vorhast. Diese Seite leitet dich zum passenden Weg — ein schneller lokaler Trial, eine Produktions-Installation hinter TLS oder die rohe Compose-Referenz, wenn du jeden Knopf besitzen willst — damit du keinen Härtungs-Spaziergang beginnst, wenn du nur herumklicken wolltest. Alle drei Wege landen auf demselben Produkt; der Unterschied ist, wie viel vom Stack du betreibst und wie haltbar das Ergebnis sein muss. Die CLI umhüllt Docker Compose für die ersten beiden, sodass es nichts von Hand zu editieren gibt, während der Referenz-Weg für Teams ist, die Compose selbst fahren. ## Tale auf einem Laptop ausprobieren Willst du eine laufende Instanz zum Durchklicken — auf deiner eigenen Maschine, ohne Domäne und ohne Härtung — ist der [Quickstart](/de/self-hosted/install/quickstart) der Weg. Installier die CLI, lauf `tale init` und dann `tale dev`, und du bist in Minuten in deiner eigenen Org angemeldet. Die CLI stellt Docker bereit, falls es fehlt, generiert jedes Secret und mountet deine Konfiguration, sodass Edits live nachladen. Das ist der richtige Weg für eine Evaluierung, eine Demo oder lokale Entwicklung gegen einen echten Stack. Wenn du dem Laptop entwächst und dasselbe Projekt auf einem echten Host willst, trägt das Trial-Projekt sich mit — `tale deploy` bringt es auf eine Domäne, ohne neu zu initialisieren. ## Tale in Produktion betreiben Wenn echter Verkehr auf der Instanz landet, ist der [Linux-Server](/de/self-hosted/install/linux-server)-Spaziergang der Weg. Er deckt TLS, eine Firewall, einen Non-root-User, den Reverse-Proxy und die operativen Haken ab, die du willst, bevor du eine Domäne darauf richtest. Die CLI macht weiterhin die Schwerarbeit — `tale deploy` fährt einen Blue-Green-Rollout ohne Ausfallzeit mit Health-Checks und Rollback — aber dieser Spaziergang fügt das Host-Level-Setup hinzu, das ein Trial überspringt. Nach dem ersten Deploy erklärt [Erster Admin](/de/self-hosted/install/first-admin) den einmaligen Setup-Wizard, der das erste Konto zum **Owner** macht — alle danach kommen per Einladung dazu, es gibt also keine offene Anmeldung zu schließen — und [CLI installieren](/de/self-hosted/install/cli-install) richtet die CLI auf einer Workstation ein, um eine entfernte Instanz zu deployen und zu upgraden. ## Die Compose-Schicht besitzen Willst du den Stack lieber aus einem Klon des Repositories fahren und Compose selbst verwalten — für Transparenz, Air-gapped-Builds oder deine eigene Automation — ist die [Docker-Compose-Referenz](/de/self-hosted/install/docker-compose-reference) der Weg. Sie dokumentiert die Basisdatei und die Overlays, die die CLI im Hintergrund generiert, sodass du sie von Hand reproduzieren oder erweitern kannst. Das ist die meiste Kontrolle und die meiste Arbeit; die meisten Teams sind mit den CLI-Wegen oben besser bedient. Dieser Weg paart sich mit dem [Linux-Server](/de/self-hosted/install/linux-server)-Spaziergang für die Host-Level-Teile (TLS, Firewall, User), die Compose allein nicht abdeckt. ## Wo das hingehört Die drei Installationswege tauschen Komfort gegen Kontrolle: der [Quickstart](/de/self-hosted/install/quickstart) ist der schnellste Weg zu einer laufenden Instanz, der [Linux-Server](/de/self-hosted/install/linux-server)-Spaziergang härtet sie für echten Verkehr, und die [Docker-Compose-Referenz](/de/self-hosted/install/docker-compose-reference) reicht dir jeden Knopf, wenn die Defaults der CLI nicht genügen. Wähl nach Haltbarkeit: ein Trial, den du wegwirfst, will den Quickstart; eine Instanz, von der dein Team abhängt, will den Produktions-Spaziergang. Einmal installiert, sind die [Konfigurations](/de/self-hosted/configuration/environment-reference)-Seiten die Quelle der Wahrheit für jede Umgebungsvariable und Provider-Datei, und der [Betreiben](/de/self-hosted/operate/container-architecture)-Abschnitt deckt Upgrades, Backups und Observability für den laufenden Stack ab. # Docker-Compose-Referenz Source: https://tale.dev/docs/de/self-hosted/install/docker-compose-reference Tale liefert eine Handvoll Docker-Compose-Dateien aus. Die Basis ist `compose.yml`; der Rest sind Overlays, die Services für spezifische Szenarien hinzufügen oder ersetzen — Entwicklung, Docs, Test. Diese Seite benennt jede Datei, sagt, wann du sie wählst, und gibt die Schichtungs-Regel, der alles andere folgt. Die Form ist absichtlich konservativ. Die Basis-Datei allein läuft in Produktion; jedes Overlay ist per `-f` opt-in und fügt nur hinzu, was es muss. Merk dir die Basis und ein einzelnes Overlay, nicht das ganze Raster. ## Ein durchgespieltes compose-up Eine produktive Single-Host-Instanz läuft allein aus der Basis: ```bash docker compose up -d ``` Ein Entwickler, der gleichzeitig an Platform und Docs hackt, schichtet zwei Overlays: ```bash docker compose -f compose.yml -f compose.dev.yml -f compose.docs.yml up -d ``` Die linkeste Datei ist die Basis; jede nachfolgende Datei merged ihre Schlüssel obendrauf. Konflikte (gleicher Service, gleicher Schlüssel) lösen mit Last-File-wins auf. Der gemergte Graph ist, was Docker hochfährt. ## Die Compose-Dateien | Datei | Anwendungsfall | Bemerkenswerte Overrides | | ----------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------- | | `compose.yml` | Produktion auf einem einzelnen Host | Die Basis — jeder Service, Healthchecks, Restart-Policy | | `compose.dev.yml` | Lokale Entwicklung mit Hot-Reload | Mountet Quellen in Container, tauscht auf Dev-Images, gibt Dev-Ports frei | | `compose.docs.yml` | Fügt den Docs-Site-Service hinzu | Fährt `tale-docs` hoch und routet `/docs` durch den Proxy | | `compose.web.yml` | Fügt den Marketing-Site-Service hinzu | Fährt `tale-web` hoch und routet `/` (Root) durch den Proxy | | `compose.test.yml` | Lässt die Platform-Test-Suite gegen den Stack laufen | Ersetzt das Platform-Image durch die test-geformte Variante | | `compose.web.test.yml` | Lässt Web-Tests laufen | Wie `web.yml`, aber die test-geformte Variante | | `compose.docs.test.yml` | Lässt Docs-Tests laufen | Wie `docs.yml`, aber die test-geformte Variante | | `compose.test.mock.yml` | Mock-gestützte Integrationstests | Tauscht Provider gegen Mock-Implementierungen | ## Services und ihre Rollen Der Basis-Graph fährt acht Container hoch: - `tale-proxy` — Caddy. TLS, Reverse-Proxy, 301s. - `tale-platform` — die TanStack-Start-App. Die User-zugewandte UI und API. - `tale-convex` — das Convex-Backend. WebSocket, Queries, Mutationen, Actions — und die In-Process-RAG-Suche, Dokument-Ingestion, das Web-Crawling und die Dokumentgenerierung, die früher separate Services waren. - `tale-db` — operatives Postgres (ParadeDB). Der persistente Speicher des Convex-Backends. - `tale-knowledge-db` — Postgres des Wissens-Korpus (ParadeDB). Die `tale_knowledge`-Datenbank mit Dokument-Chunks, Embeddings und gecrawlten Seiten, auf Port 5433, damit sie nie mit `tale-db` auf 5432 kollidiert. - `tale-sandbox-llm-gateway` — das LLM-Gateway für In-Sandbox-Coding-Agents (gepinntes externes Image). - `tale-sandbox-egress` und `tale-sandbox` — die Sandbox-Ebene. Run-Code-Container hinter einem Egress-Proxy (standardmäßig offen; sperrbar mit `SANDBOX_EGRESS_ALLOWLIST`), zugleich die Headless-Browser-Laufzeit, die das Convex-Backend für Web-Render und Dokumentgenerierung aufruft. Der Stack ist jetzt vollständig TypeScript — es gibt keinen Python-Service im Graph. [Container-Architektur](/de/self-hosted/operate/container-architecture) vertieft, was was besitzt. ## Overrides Operator-Anpassungen gehören in ein zusätzliches Overlay, nicht in Edits an den ausgelieferten Dateien. Erstell eine `compose.local.yml` mit den Overrides, die du brauchst: ```yaml services: platform: environment: - LOG_LEVEL=debug ``` Fahr den Stack mit dem lokalen Overlay zuletzt geschichtet hoch: ```bash docker compose -f compose.yml -f compose.local.yml up -d ``` Dieses Muster hält `git pull` sauber — keine Merge-Konflikte auf den ausgelieferten Dateien. Dasselbe Muster funktioniert für jedes benutzerdefinierte Volume-Mount, jeden benutzerdefinierten Port oder jedes Environment-Override. ## Profile Ein Service in der Basis-Datei nutzt ein Docker-Compose-Profil. Profile lassen einen Service im Graph existieren, aber nicht starten, ausser sein Profil ist aktiviert. Das im Einsatz befindliche Profil ist `controller` — der Opt-in-Sidecar `tale-controller`, der den Convex-Container auf eine signierte Anfrage neu startet, damit eine Datenresidenz-Änderung greift, ohne der Plattform Docker-Socket-Zugriff zu geben. Aktivier es mit: ```bash docker compose --profile controller up -d ``` ## Wo das hineinpasst Die Compose-Referenz ist das Raster des Betreibers für den Source-Tree. Für das Innere jedes Containers deckt die Seite [Container-Architektur](/de/self-hosted/operate/container-architecture) Verantwortlichkeiten ab; für die Variablen, die die Container beim Boot lesen, ist die [Environment-Referenz](/de/self-hosted/configuration/environment-reference) die Quelle der Wahrheit. # Produktions-Linux-Server-Installation Source: https://tale.dev/docs/de/self-hosted/install/linux-server Dieser Spaziergang nimmt die [Quickstart](/de/self-hosted/install/quickstart)-Form und härtet sie für Produktionsverkehr. Das Ergebnis ist ein einzelner Linux-Host, der Tale hinter echtem TLS betreibt, mit einer Firewall, einem Non-root-Operator-User und den operativen Defaults, die das Team treffen sollte, bevor es User auf die URL zeigt. Der Spaziergang zielt auf ein aktuelles Ubuntu LTS oder Debian; Befehle übersetzen eins-zu-eins auf RHEL-Familie-Distros mit `dnf` statt `apt`. Spring keinen Schritt — die Reihenfolge zählt, und jeder Schritt setzt voraus, dass der vorherige sauber gelandet ist. ## Bevor du beginnst Du brauchst: - Eine VM oder einen Bare-Metal-Host mit mindestens 8 GB RAM, 4 vCPU und 100 GB Disk. Der Speicher wächst mit Anhängen und Wissen. - Einen DNS-A-Eintrag, der auf die öffentliche IP des Hosts zeigt. Ohne DNS kann Let's Encrypt kein Zertifikat ausstellen. - Ports 80, 443 aus dem öffentlichen Internet erreichbar für die TLS-Ausstellung; SSH auf welchem Port auch immer deine Operator-Policy sagt. - Sudo auf dem Host. ## Schritt 1 — Die Box provisionieren Aktualisiere und installier die Grundlagen: ```bash sudo apt update && sudo apt upgrade -y sudo apt install -y curl git ufw ``` Erstell einen Non-root-Operator-User namens `tale`: ```bash sudo adduser tale sudo usermod -aG sudo,docker tale ``` Wechsle zu diesem User (`sudo su - tale`) für den Rest des Spaziergangs. Tale als root zu betreiben holt einen höheren Wirkungsradius für keinen Nutzen; der Rest der Schritte setzt den `tale`-User voraus. ## Schritt 2 — Docker installieren ```bash curl -fsSL https://get.docker.com | sudo sh sudo systemctl enable --now docker ``` Verifizier mit `docker run hello-world`. Kann der User Docker nicht ohne sudo laufen lassen, melde dich ab und wieder an, um die `docker`-Gruppen-Mitgliedschaft zu übernehmen. ## Schritt 3 — Firewall und Reverse-Pfad konfigurieren Erlaub nur, was Tale braucht: ```bash sudo ufw default deny incoming sudo ufw default allow outgoing sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable ``` Stellst du Tale einen bestehenden Reverse-Proxy auf demselben Host vor (selten bei einer Single-Host-Installation), setze `TLS_MODE=external` in `.env` und passe die Firewall entsprechend an. Der Caddy-Container innerhalb von Tale terminiert TLS standardmässig. ## Schritt 4 — Tale ziehen ```bash git clone https://github.com/tale-project/tale.git cd tale cp .env.example .env ``` Setze `HOST`, `SITE_URL` und generier die vier Secrets wie im [Quickstart](/de/self-hosted/install/quickstart). Der Produktions-Diff gegenüber dem Quickstart lebt in Schritt 5 (TLS) und den operativen Haken am Ende dieses Spaziergangs. ## Schritt 5 — TLS via Let's Encrypt Öffne `.env` und setze: | Variable | Wert | | ----------- | ------------------------------ | | `TLS_MODE` | `letsencrypt` | | `TLS_EMAIL` | Ein Ops-Postfach, das du liest | Caddy stellt das Zertifikat aus und erneuert es automatisch über den DNS-Eintrag aus den Voraussetzungen. Der erste Boot wartet auf das Zertifikat; rechne mit einer Verzögerung von einer Minute beim ersten `docker compose up -d`, während die ACME-Challenge läuft. ## Schritt 6 — Erster Boot ```bash docker compose up -d docker compose ps ``` Jeder Service sollte `running` oder `healthy` zeigen. Folg dem **Schritt 4 — Den ersten Admin erstellen** aus dem [Quickstart](/de/self-hosted/install/quickstart), um im Dashboard zu landen. Öffne `SITE_URL` über `https://` — der Browser sollte nicht vor dem Zertifikat warnen. ## Schritt 7 — Operative Haken Bevor du User auf die URL zeigst, machen dir drei Haken später das Leben leichter: - **Backups.** Richt dein bestehendes Snapshot-Tooling auf `db-data` und das Object-Store-Volume — siehe [Backups und Restore](/de/self-hosted/operate/backups-and-restore). - **Logs.** Tale loggt auf stdout. Hat der Host journald, trägt `journalctl -u docker` alles; sonst pipe zu deinem Aggregator. - **Metriken.** Setze `METRICS_BEARER_TOKEN` in `.env` und scrap `/metrics` aus deinem Prometheus — siehe [Observability-Konfiguration](/de/self-hosted/configuration/observability-config). ## Port-Tabelle | Port | Richtung | Zweck | Erforderlich | | ---- | -------- | ---------------------------------------- | ----------------- | | 22 | inbound | SSH | ja, eingeschränkt | | 80 | inbound | HTTP, genutzt für ACME und 301 auf HTTPS | ja | | 443 | inbound | HTTPS, primärer Verkehr | ja | | 53 | outbound | DNS | ja | | 443 | outbound | Modell-Provider, Image-Pulls | ja | ## Fehlersuche - **Let's-Encrypt-Ausstellung scheitert.** DNS muss auf die öffentliche IP dieses Hosts aus dem öffentlichen Internet auflösen, und Port 80 muss aus dem öffentlichen Internet erreichbar sein. Lauf `curl -I http://$HOST` von einer anderen Maschine; trifft es die Caddy-Challenge, läuft der Pfad. - **Container können Modell-Provider nicht erreichen.** Die ausgehende Firewall des Hosts blockt vielleicht; verifizier mit `docker compose exec platform curl -I https://api.openai.com`. - **TLS-Zertifikat-Erneuerungen scheitern später.** Caddy erneuert 30 Tage vor Ablauf; Fehler zeigen sich in `docker compose logs proxy`. Die zwei häufigen Ursachen sind eine abgelaufene `TLS_EMAIL`-Mailbox und eine DNS-Änderung, die den Eintrag gebrochen hat. ## Wo das eingesetzt wird Du hast jetzt eine produktions-geformte Installation auf einem Host. Zwei Folgeaufgaben gehören in den Kalender — [Backups und Restore](/de/self-hosted/operate/backups-and-restore) und [Härten](/de/self-hosted/operate/security/hardening). Wächst dein Massstab über einen Host hinaus (Faustregel: etwa hundert gleichzeitige User auf der empfohlenen Spec), lebt die Multi-Host-Architektur unter [Container-Architektur](/de/self-hosted/operate/container-architecture). # Den ersten Admin erstellen Source: https://tale.dev/docs/de/self-hosted/install/first-admin Eine brandneue Tale-Instanz hat noch keine User. Die erste Person, die sie öffnet, durchläuft einen einmaligen Setup-Wizard, der ihr Konto anlegt, sie anmeldet, sie zum **Owner** macht und die erste Organisation benennt — kein Bootstrap-Key, keine manuelle Beförderung. Dieser Spaziergang deckt diesen ersten Lauf ab, wie Teammitglieder danach dazukommen und wo du den Convex-Dashboard-Admin-Key bekommst, falls du das Backend mal direkt inspizieren musst. Das Eine, was du aus älteren Anleitungen verlernen musst: Die erste Anmeldung fragt nicht mehr nach einem Admin-Key. Tale ist nach dem ersten Konto nur per Einladung zugänglich, also gibt es auch keine offene Sign-up-Seite, die du abriegeln müsstest. ## Bevor du beginnst Hab die Instanz laufen und unter `SITE_URL` erreichbar. Verifizier mit: ```bash docker compose ps ``` Jeder Service sollte `running` oder `healthy` zeigen. Ist einer ungesund, benennt die [Fehlersuche](/de/self-hosted/operate/observability/troubleshooting) die vier häufigen Ursachen. ## Den Setup-Wizard durchlaufen Öffne `SITE_URL`. Da es noch keine User gibt, schickt Tale dich direkt in den Setup-Wizard — es gibt keine separate Sign-up-Seite zu suchen, denn der Login-Bildschirm leitet eine leere Instanz automatisch ins Setup um. Der Wizard legt dein Konto an und meldet dich mitten im Flow an, dann benennt er deine erste Organisation. Der Provider-Schritt ist optional: Überspring ihn und füg einen Key später unter **Einstellungen > KI-Anbieter** hinzu, oder verbinde OpenRouter jetzt, um sofort zu chatten. Hol dir einen Key auf [openrouter.ai/keys](https://openrouter.ai/keys). Der Abschluss-Schritt setzt dich ins Dashboard. ## Bestätigen, dass du der Owner bist Das erste Konto auf einer frischen Instanz ist automatisch der **Owner** — kein Key zum Einfügen, kein Beförderungsschritt. Bestätig unter **Einstellungen > Personen**, dass deine Zeile das Owner-Badge trägt. ## Wie neue Leute dazukommen Es gibt kein Self-Service-Signup. Sobald ein Owner existiert, leitet `SITE_URL/sign-up` Besucher auf den Login-Bildschirm um, sodass niemand sich selbst ein Konto anlegen kann. Füg Teammitglieder per Einladung unter **Einstellungen > Personen** hinzu; jede Einladung trägt die Rolle, mit der das neue Mitglied startet. Das vollständige Rollenmodell steht in [Mitglieder und Rollen](/de/platform/admin/members-and-roles). ## Den Convex-Dashboard-Admin-Key holen Der Admin-Key spielt in den obigen Schritten keine Rolle — er schaltet nur das **Convex-Dashboard** frei, die Low-Level-Ansicht der Backend-Datenbank. Der Key ist deterministisch: Er wird aus `INSTANCE_SECRET` abgeleitet, bleibt also über Neustarts hinweg gleich und rotiert nicht. Hol ihn so, wie es zu deiner Installation passt: - Mit der CLI: `tale convex admin` findet den Platform-Container und gibt den Key aus. `tale dev` gibt ihn ebenfalls aus, sobald die Services gesund sind. - Aus einem Git-Klon: `./scripts/get-admin-key.sh` aus dem Repo-Root. Öffne `SITE_URL/convex-dashboard`, gib `SITE_URL` als Deployment-URL ein und füg den Key ein, wenn du danach gefragt wirst. ## Fehlersuche - **Der Wizard erschien nicht — du landest auf dem Login-Bildschirm.** Es gibt bereits User auf dieser Instanz; der Wizard läuft nur auf einer wirklich leeren. Melde dich stattdessen an, oder lass dich von einem bestehenden Owner unter **Einstellungen > Personen** einladen. - **Ein Service ist ungesund.** Der Platform-Container ist nicht vollständig oben. `docker compose ps` sagt, welcher Service scheitert; `docker compose logs platform` zeigt warum. - **Das Dashboard lehnt den Admin-Key ab.** Der Key ist deterministisch aus `INSTANCE_SECRET`, eine Ablehnung heisst also meist, dass sich `INSTANCE_NAME` und `INSTANCE_SECRET` zwischen Platform- und Convex-Service unterscheiden, oder die Deployment-URL falsch ist — nimm `SITE_URL`. Generier mit `tale convex admin` neu, um sicherzugehen, dass du den aktuellen Wert kopiert hast. ## Wo das eingesetzt wird Du hast jetzt einen Owner und eine Org und weisst, dass der Admin-Key ein Backend-Inspektionswerkzeug ist, kein Teil der Anmeldung. Der erste Lauf ist absichtlich keylos: Öffne die URL, der Wizard macht dich zum Owner, und alle anderen kommen per Einladung dazu. Die nächsten Schritte für den Kalender sind, den Rest der Admins einzuladen (unter **Einstellungen > Personen**), einen Modell-Provider hinzuzufügen und den ersten Agent zu veröffentlichen — der [Cloud-Onboarding](/de/cloud/onboarding)-Spaziergang ist von hier an identisch, ausser der URL. # Die tale-CLI installieren Source: https://tale.dev/docs/de/self-hosted/install/cli-install Die `tale`-CLI ist der empfohlene Weg, Tale zu betreiben und zu bedienen. Der [Quickstart](/de/self-hosted/install/quickstart) nutzt sie bereits, um eine Instanz lokal mit `tale init` und `tale dev` aufzustellen; diese Seite ist die andere Hälfte — die CLI auf einer Workstation installieren, damit sie eine _entfernte_ Instanz fahren kann: neue Versionen deployen, Migrationen ausführen und Diagnostiken einfangen, ohne dass du dir jede `docker compose`-Invokation merken musst. Alles, was die CLI macht, lässt sich auch direkt mit `docker compose` und `ssh` machen, sodass ein Team, das schon tief in der eigenen Automatisierung steckt, bei Compose bleiben kann. Für alle anderen ist die CLI der kürzere Weg, und der Rest der self-hosted Docs setzt voraus, dass sie installiert ist. ## Bevor du beginnst Du brauchst: - Eine Workstation mit macOS, Linux oder Windows 10+. - SSH-Zugriff auf den Host, auf dem deine Tale-Instanz läuft, mit einem Operator-User, der `docker compose` ausführen kann. Der Installer lädt ein Release-Binary von GitHub. Unternehmensnetzwerke, die Raw-Content-Downloads blockieren, müssen `raw.githubusercontent.com` und `github.com` zulassen. ## Schritt 1 — 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 ``` Beide Installer erkennen Betriebssystem und CPU-Architektur, ziehen das passende Release-Binary aus dem neuesten GitHub-Release und legen es im `PATH` ab (`/usr/local/bin/tale` oder `%LOCALAPPDATA%\Programs\tale\tale.exe`) — ist das Installationsverzeichnis nicht beschreibbar, fragt der Installer nach `sudo`. Release-Binaries gibt es für macOS auf Apple Silicon und Intel sowie für Linux auf x86_64 und arm64; Windows-on-ARM-Maschinen führen das x64-Binary über die eingebaute Emulation aus. Auf einer Architektur ohne Release-Binary bricht der Installer mit einer klaren Meldung ab und verweist auf den Build aus dem Quellcode. Um eine Version festzuhalten, setze die Environment-Variable `VERSION`, bevor du in den Installer pipest; das Installationsverzeichnis wählst du mit `INSTALL_DIR` selbst. | OS | Installer-Skript | | ------- | ------------------------- | | macOS | `scripts/install-cli.sh` | | Linux | `scripts/install-cli.sh` | | Windows | `scripts/install-cli.ps1` | ## Schritt 2 — Verifizieren ```bash tale --version ``` Die CLI gibt ihre Version aus. Wird der Befehl nicht gefunden, hat der Installer das Binary ausserhalb des `PATH` abgelegt — die Installer-Ausgabe benennt das Zielverzeichnis. ## Schritt 3 — Konfiguration prüfen Es gibt kein `tale config set` — alles, was die CLI braucht, liegt im Projekt, das `tale init` angelegt hat. Führ jeden `tale`-Befehl aus diesem Verzeichnis heraus aus (die CLI läuft den Baum hoch, um `tale.json` zu finden), und prüf, dass es aufgelöst wird: ```bash tale config show ``` Der Host, auf dem der Proxy antwortet, die TLS-Einstellungen und alle Secrets liegen im `.env` des Projekts. Um den Host zu ändern, bearbeite dort `HOST` oder übergib `--host` an `tale dev` / `tale deploy`. Um einen entfernten Host zu betreiben, richte den Docker-Kontext deiner Shell (oder `DOCKER_HOST`) darauf aus — die CLI spricht denselben Docker-Endpunkt an wie jeder `docker`-Befehl. Der Admin-Key fürs Convex-Dashboard ist von der CLI-Konfiguration getrennt — er hat mit der Anmeldung nichts zu tun und ist deterministisch (abgeleitet aus `INSTANCE_NAME` und `INSTANCE_SECRET`, bleibt also über Neustarts hinweg gleich). Erzeug ihn mit `tale convex admin`, wenn du das Backend inspizieren willst (siehe [Erster Admin](/de/self-hosted/install/first-admin)). ## Schritt 4 — tale deploy ausführen ```bash tale deploy ``` `tale deploy` liefert immer die Version der CLI selbst aus: Es zieht die Images dieser Version, restartet die betroffenen Container in der richtigen Reihenfolge und führt Schema-Migrationen aus — auf eine andere Version wechselst du vorher mit `tale update`. Es ist der unterstützte Ersatz für das längere `docker compose pull && docker compose up -d`-Tänzchen. Bevorzugst du Compose direkt, lebt derselbe Effekt in [Upgrades](/de/self-hosted/operate/upgrades). ## 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**. - Jedes Flag ist **optional** — weglassen ergibt das Standardverhalten. - Ein Flag der Form `--flag <wert>` **erfordert einen Wert**, wenn du es nutzt (z. B. `--port 8443`); ein blosses 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. Führe `tale <befehl> --help` für die massgebliche Liste deiner installierten Version aus. **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, menschliche Meldungen auf stderr; unterstützt von `status`, `config show` und `migrate status`. - `--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 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. - `-d, --detach` — im Hintergrund laufen statt Logs zu streamen. - `-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` — Blue-Green-Deployment ohne Ausfallzeit der aktuellen CLI-Version. Beim ersten Deploy fragt es nach deiner Produktiv-Domain und der Let's-Encrypt-E-Mail (oder übergib `--host`). - `--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. ### 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` — Snapshot aller Daten-Volumes in das Projekt-Backups-Volume. Keine Argumente. `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` — diese Tale-Instanz auf eine neue Version bewegen: zuerst das CLI-Binary aktualisieren, dann die Projektdateien synchronisieren; danach `tale deploy` ausführen, um die Container zu rollen. Die CLI gleicht sich bei jedem Befehl ohnehin an die Instanz-Version an, also brauchst du das nur, um die Version bewusst zu wechseln. - `-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 neu provisionieren und die sicheren, ausstehenden Daten-Migrationen auf das laufende Deployment anwenden — dieselben idempotenten Schritte, die jeder Deploy ausführt, nur auf Zuruf. Die Subcommands geben dir gezielte, umkehrbare Kontrolle: `migrate status` zeigt angewendete und ausstehende Migrationen, `migrate up [--to <version>]` wendet ausstehende an (destruktive Schritte brauchen `-y, --yes` oder `--step`), `migrate down --to <version>` rollt zurück. `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 die benutzereigene Konfiguration (`~/.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. - `-f, --force` — die Bestätigungsabfrage überspringen (entfernt nur das Binary; die optionalen Aufräumschritte brauchen weiterhin `--purge`). - `--purge` — zusätzlich `~/.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` — CLI-Konfiguration verwalten. Mit dem Unterbefehl `show` die aufgelöste Konfiguration ausgeben. ### Erweitert `tale auth reset-owner` — die Zugangsdaten des Owner-Kontos zurücksetzen. - `-e, --email <email>` — eine neue Owner-E-Mail-Adresse setzen. - `-p, --password <password>` — ein neues Owner-Passwort setzen. `tale convex admin` — einen Admin-Key für das Convex-Dashboard erzeugen. Keine Argumente. ## 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. - **Das Convex-Dashboard weist den Admin-Key ab.** Die Anmeldung fragt nie nach dem Key — nur das Dashboard. Der Key ist deterministisch (abgeleitet aus `INSTANCE_NAME` und `INSTANCE_SECRET`); eine Ablehnung heißt also meist, dass sich diese Werte zwischen Platform- und Convex-Service unterscheiden, oder die Deployment-URL falsch ist — nimm `SITE_URL`. Generier mit `tale convex admin` neu, um sicherzugehen, dass du den aktuellen Wert kopiert hast. - **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`). ## Wo das eingesetzt wird Sobald die CLI verdrahtet ist, schrumpft die tägliche Oberfläche des Betreibers auf eine Handvoll Subbefehle. Welche Seiten du als Nächstes liest, hängt davon ab, wozu du gekommen bist — [Upgrades](/de/self-hosted/operate/upgrades) für Versionsbumps, [Backups und Restore](/de/self-hosted/operate/backups-and-restore) für Snapshot-Übungen, [Container-Architektur](/de/self-hosted/operate/container-architecture) dafür, was die CLI beim Deploy restartet. # Tale-Dokumentation Source: https://tale.dev/docs/de Tale ist der Orchestrator für KI-Agents. Du chattest mit Modellen über deine eigenen Dokumente, baust Agents, die eine Aufgabe von Anfang bis Ende übernehmen, lässt Automatisierungen im Hintergrund laufen und verwaltest Kunden-Konversationen in einem einzigen Posteingang — mit deiner Wahl an KI-Anbietern und deinen Daten in einer Region, die du selbst bestimmst. Jedes Feature, jede API und jede Rolle ist in beiden Editionen identisch; der einzige Unterschied ist, wer den Stack betreibt. Starte mit dem Quickstart und folge dann dem Einstieg, der zu deiner Rolle passt. <CardGroup cols="1"> <Card title="Quickstart — in 5 Minuten zur ersten Agent-Antwort" icon="zap" href="/de/get-started/quickstart"> Von einer laufenden Instanz zu einer funktionierenden Chat-Antwort, auf Cloud oder deiner eigenen Maschine. </Card> </CardGroup> ## Wähl deinen Einstieg Vier Einstiege für den ersten Tag, einer pro Rolle. Jeder dauert rund 15 Minuten und endet mit etwas, das funktioniert. <CardGroup cols="2"> <Card title="Ich nutze Tale" icon="message-circle" href="/de/get-started/members"> Dein erster Chat, dein erstes Dokument, dein erstes Projekt — der erste Tag als Mitglied. </Card> <Card title="Ich baue Agents" icon="bot" href="/de/get-started/editors"> Veröffentliche einen minimalen Agent und sieh ihm beim Antworten zu — der erste Tag als Redakteur. </Card> <Card title="Ich binde Tale an" icon="code" href="/de/get-started/developers"> Erstelle einen API-Schlüssel und mach deine erste authentifizierte Anfrage — der erste Tag als Entwickler. </Card> <Card title="Ich betreibe den Arbeitsbereich" icon="shield" href="/de/get-started/admins"> Richte den Arbeitsbereich ein, lade das Team ein, verbinde einen Anbieter — der erste Tag als Admin. </Card> </CardGroup> ## Wähl deine Edition <CardGroup cols="2"> <Card title="Cloud" icon="cloud" href="/de/cloud"> Tale betreibt den Stack — wähl das, wenn das Betreiben von Infrastruktur nicht der richtige Ort für die Stunden deines Teams ist. </Card> <Card title="Selbst gehostet" icon="server" href="/de/self-hosted"> Installiere Tale in deiner eigenen VPC, auf On-Premise-Hardware oder in einer Air-gapped-Umgebung. </Card> </CardGroup> ## Tiefer eintauchen <CardGroup cols="3"> <Card title="Plattform" icon="layout-dashboard" href="/de/platform"> Die kanonische Feature-Referenz, identisch für Cloud und selbst gehostet. </Card> <Card title="Tutorials" icon="route" href="/de/tutorials/overview"> Rollenbasierte Walkthroughs von „Ich möchte X tun" zum funktionierenden Ergebnis. </Card> <Card title="Entwicklung" icon="terminal" href="/de/develop/overview"> REST API, Webhooks, Integrations-SDK, Contributor-Workflows. </Card> </CardGroup> ## Wo das hingehört Sobald du einen Einstieg durchlaufen hast, ist der Rest der Dokumentation einen Klick entfernt: [Plattform](/de/platform) ist die kanonische Referenz für jedes nutzersichtbare Feature, und die [Tutorials](/de/tutorials/overview) gehen bei kompletten Aufgaben in die Tiefe. Quellcode, Issues und Release-Ankündigungen leben auf [GitHub](https://github.com/tale-project/tale). # Entwicklung Source: https://tale.dev/docs/de/develop/overview Entwicklung ist der Abschnitt für Integratoren und Contributors — alle, die Tale an ein anderes System anbinden, auf der API aufsetzen oder eine Änderung am Quellcode liefern. Die Seiten hier beschreiben die externe Oberfläche (REST, Webhooks, OpenAI-kompatible Endpoints) und den Contributor-Workflow. Wenn du innerhalb des Produkts als Entwickler-Rolle arbeitest (Agents, Workflows, eigene Tools), deckt der Reiter Plattform deinen Alltag ab; Entwicklung ist dann gefragt, wenn du außerhalb des Produkts stehst und über die Leitung mit ihm sprichst. ## Seiten in diesem Abschnitt <CardGroup cols="2"> <Card title="API-Referenz" icon="code" href="/de/develop/api-reference"> Endpoints, Authentifizierung, OpenAI-kompatible Endpoints, Fehlermodell, Versionierung. </Card> <Card title="Webhooks" icon="webhook" href="/de/develop/webhooks"> Ausgehend (Tale → du) und eingehend (du → Tale), Signieren, Idempotenz, Wiederholungen. </Card> <Card title="KI-gestützte Entwicklung" icon="sparkles" href="/de/develop/ai-assisted-development"> Tale-Agents nutzen, um Tale-Workflows zu schreiben; die `.agents/`-Skill-Dateien. </Card> <Card title="Integrationen" icon="plug" href="/de/develop/integrations"> Drittanbieter-Integrationen aus Entwicklersicht. </Card> <Card title="Status-Seite" icon="activity" href="/de/develop/status-page"> Vorfallsmeldungen für Cloud, Metrik-Verweise für selbst gehostet. </Card> <Card title="Rate Limits" icon="gauge" href="/de/develop/rate-limits"> Limits pro Key, pro IP, pro Organisation und wie ein 429 zu lesen ist. </Card> </CardGroup> ## Wo das hingehört Entwicklung ist der kleinste Abschnitt, weil die meisten Nutzer ihn nie brauchen; das Publikum konzentriert sich auf zwei Rollen (Entwickler im Produkt, Contributor außerhalb), ist aber für beide tragend. Wenn du etwas Externes an Tale anbindest, ist [API-Referenz](/de/develop/api-reference) die erste Lektüre; wenn du am Quellcode beiträgst, ist [Mitwirken](/de/self-hosted/contributing-docker) — unter dem Reiter Selbst gehostet — die richtige. # API-Referenz Source: https://tale.dev/docs/de/develop/api-reference Die Tale-API ist die Oberfläche, zu der Integratoren greifen, wenn sie ausserhalb des Produkts sind und es skripten wollen. Authentifizierung ist ein API-Key in einem Header; die Datenebene ist JSON über HTTPS; eine Teilmenge der Chat-Endpoints spricht das OpenAI-Chat-Completions-Format, sodass bestehende OpenAI-Client-Bibliotheken unverändert funktionieren. Diese Seite ist die kanonische Inventur der API-Oberfläche, des Auth-Modells und der Fehler-Form. Sie listet nicht jedes Payload-Feld auf — das lebt neben jeder Endpoint-Gruppe auf den verlinkten Unterseiten. Lies sie, bevor du die API aufrufst; komm zurück, wenn du nicht sicher bist, welcher Header den Key trägt oder was ein 429 bedeutet. ## Ein durchgespielter Request Der kürzeste nützliche Request — liste die Agents, die dein Key sehen kann — ist ein curl: ```bash curl -sS https://your-host.example.com/api/v1/agents \ -H "Authorization: Bearer $TALE_API_KEY" \ -H "Accept: application/json" ``` Eine erfolgreiche Antwort ist JSON: `{ "agents": [ { "id": "...", "name": "...", "visibleInChat": true, ... }, ... ] }`. Jeder List-Endpoint gibt dieselbe Form zurück — ein Top-Level-Objekt mit einer Array-Eigenschaft, die nach der Ressource benannt ist. ## Authentifizierung API-Keys werden in der UI unter **Einstellungen > API-Keys** von jedem mit der Rolle Entwickler oder höher erzeugt. Jeder Key hat einen Namen, einen Besitzer und einen Scope; der Scope folgt der Rolle des ausgebenden Benutzers zur Zeit der Erstellung. Keys werden bei der Erstellung einmal gezeigt; Tale zeigt den rohen Key nie wieder an. Übergib den Key als Bearer-Token: `Authorization: Bearer <key>`. Der Key authentifiziert den Request; der Organisations-Kontext wird aus dem Key abgeleitet. Ein Key kann nicht ausserhalb seiner ausstellenden Organisation genutzt werden. Cookies authentifizieren die Browser-Session; API-Aufrufe aus dem Browser innerhalb des Produkts nutzen Cookies. Server-seitige Skripte nutzen den API-Key. ## Endpoint-Gruppen | Gruppe | Methode | Pfad | Auth nötig | Hinweise | | ------------------------------------------------ | ------------ | ---------------------------- | ---------- | ---------------------------------------------------------- | | Agents | verschiedene | `/api/v1/agents/...` | API-Key | List, get, run. | | Chat | verschiedene | `/api/v1/chat/...` | API-Key | Stream Chat-Completions gegen einen Agent oder ein Modell. | | OpenAI-kompatibel | POST | `/api/v1/chat/completions` | API-Key | OpenAI-Chat-Completions-Form; bestehende SDKs nutzen. | | OpenAI-kompatibel | POST | `/api/v1/images/generations` | API-Key | Bilder generieren; OpenAI-Images-Form. | | OpenAI-kompatibel | GET | `/api/v1/models` | API-Key | Verfügbare Modelle im OpenAI-Format auflisten. | | Workflows | verschiedene | `/api/v1/workflows/...` | API-Key | Run per Slug, Zeitpläne, Webhooks, Ausführungen. | | Workflow-Webhooks | POST | `/api/workflows/wh/<token>` | URL-Token | Einen webhook-getriggerten Workflow von außen auslösen. | | Wissen — Dokumente | verschiedene | `/api/v1/documents/...` | API-Key | Upload, list, get, delete. | | Wissen — Kunden, Produkte, Lieferanten, Websites | verschiedene | `/api/v1/<entity>/...` | API-Key | List, get, create, update. | | Konversationen | verschiedene | `/api/v1/conversations/...` | API-Key | List nach Status, get, write messages. | | Dateien | verschiedene | `/api/v1/files/...` | API-Key | Upload, get, delete. Von Uploads genutzt. | Exakte Feld-Formen für jeden Endpoint leben im OpenAPI-Dokument, das die Plattform zur Build-Zeit emittiert; lad es in einem Swagger- oder Stoplight-Viewer, um Request- und Response-Schemas mit Beispielen zu sehen. Die Endpoint-Gruppen in der Tabelle oben sind die High-Level-Inventur; das OpenAPI-Dokument ist die Feldebenen-Referenz. ## OpenAI-kompatible Endpoints `POST /api/v1/chat/completions` akzeptiert einen Payload in OpenAI-Chat-Completions-Form und gibt eine streaming- oder nicht-streaming-Antwort in derselben Form zurück. Das Feld `model` wird als Agent-ID interpretiert — übergib eine Agent-ID, um durch die Anweisungen, das Wissen und die Tools dieses Agents zu routen. Übergib einen rohen Modellnamen (z. B. `gpt-4o`), um Agents zu überspringen und den Provider direkt aufzurufen. Bestehende OpenAI-SDKs funktionieren mit einer Änderung: zeig die Base-URL auf `https://your-host.example.com/api/v1` und tausch den API-Key. Streaming nutzt Server-Sent Events. ### Vision Um ein Bild zu senden, gib der User-Nachricht statt eines Strings ein Array-`content` aus Teilen — einen `text`-Teil plus einen oder mehrere `image_url`-Teile, jeder mit einer `data:`-URL oder einer öffentlichen `https`-URL. Das ist die Standard-OpenAI-Vision-Form, ein SDK, das multimodale Nachrichten schon baut, braucht also keine Änderung. Ein einfacher String-`content` funktioniert weiter für reine Text-Turns; nur Bild-Input braucht die Array-Form. ### Bildgenerierung `POST /api/v1/images/generations` nimmt `{ model, prompt, n?, response_format? }` und gibt die OpenAI-Images-Form zurück — `{ created, data: [...] }`. `response_format` ist `url` (Standard — jeder Eintrag ist eine Download-URL) oder `b64_json` (jeder Eintrag ist Base64-Bild-Bytes); `n` ist auf 4 gedeckelt. Ruf es über das `images.generate` eines beliebigen OpenAI-SDKs auf. Ein Bildgenerierungs-Modell an `/api/v1/chat/completions` zu übergeben funktioniert ebenfalls: Das generierte Bild kommt an der Assistant-Nachricht als `choices[0].message.images[]` zurück — jeweils eine `image_url` — passend zur Konvention bildfähiger Gateways, sodass der Aufruf gegen ein zurückgegebenes Bild abgerechnet wird statt gegen ein verworfenes. Um ein bestehendes Bild zu bearbeiten, schick dieselbe Anfrage mit einem `text`-Teil und einem `image_url`-Teil mit einer `data:`-URL an ein Modell, das Bearbeitung unterstützt; das bearbeitete Bild kommt auf demselben Weg zurück. Nur `data:`-URLs werden als Bearbeitungs-Eingaben gelesen — Tale holt eine `http`-Bild-URL nie serverseitig. ## Fehlermodell Fehler landen als JSON: `{ "error": { "code": "<symbol>", "message": "<human>", "details"?: { ... } } }`. Der HTTP-Status ist einer von: - **400** — fehlerhafter Request (fehlendes Feld, falscher Typ). - **401** — fehlender oder ungültiger API-Key. - **403** — der Key ist gültig, hat aber nicht die Rolle, die für die Aktion nötig ist. - **404** — die Ressource existiert nicht oder der Key kann sie nicht sehen. - **409** — Konflikt (z. B. doppelter Idempotency-Key mit anderem Body). - **422** — semantisch ungültig (z. B. ein Agent, auf den ein Workflow-Trigger zeigt, ist archiviert). - **429** — Rate-Limit getroffen. Siehe [Rate Limits](/de/develop/rate-limits). - **500** — interner Fehler. Das `details`-Feld des Bodys hat eine Request-ID, die du im Support zitieren kannst. Der `code` ist ein Symbol (`unauthorized`, `forbidden`, `agent_not_found`, …); die `message` ist menschenlesbar. Clients sollen auf `code` verzweigen, nicht auf die menschliche Nachricht. ## Idempotenz Jeder Write-Endpoint akzeptiert einen `Idempotency-Key`-Header. Der erste Request mit einem gegebenen Key gelingt; nachfolgende Requests mit demselben Key geben dieselbe Antwort zurück, ohne erneut auszuführen. Der Key ist 24 Stunden gültig. Idempotenz ist Pflicht für Webhook-Trigger-Aufrufe — das Quellsystem muss einen stabilen Key pro logischem Ereignis schicken, damit Retries den Workflow nicht doppelt feuern. ## Versionierung Die API ist nach URL-Präfix versioniert: heute `/api/v1/`. Breaking Changes erscheinen unter einem neuen Präfix; das alte Präfix bleibt mindestens eine Minor-Version verfügbar. Nicht-breaking Ergänzungen landen im aktuellen Präfix. Die Release Notes nennen die API-Version, gegen die jede Release ausgeliefert wird; pinne deine Client-Bibliothek in Produktion auf die aktuelle Version. ## Wo das hingehört Die API ist die Naht zwischen Tale und allem ausserhalb. Webhooks sind die andere Hälfte — für Events, die Tale zu dir pushen muss, oder für dich, an Tales Workflows zu pushen, behandelt die [Webhooks-Referenz](/de/develop/webhooks) die Signier- und Idempotenz-Regeln. Wenn du innerhalb des Produkts als Entwickler-Rolle baust — Agents, Workflows, eigene Tools — ist der [Plattform-Reiter](/de/platform) dein Alltag; diese Seite ist für aussen. # Rate-Limits Source: https://tale.dev/docs/de/develop/rate-limits Tales REST-API ist pro Schlüssel und pro Org rate-limitiert. Die Defaults sind auf normalen Anwendungsverkehr ausgelegt — Bursts sind in Ordnung, anhaltendes Hämmern gibt 429 zurück. Wenn du ein Limit triffst, trägt die Antwort die Header, die du brauchst, um sauber zurückzuschalten; der falsche Zug (Retry ohne Verzögerung, Retry für immer) verschärft die Drosselung nur. Lies das, wenn du einen Client verdrahtest, der die API geplant oder unter Last aufruft. Komm zurück, wenn eine bisher gesunde Integration plötzlich 429 zurückgibt — die Antwort ist meist ein fehlendes Backoff, nicht eine fehlende Kapazitätszuteilung. ## Ein durchgespielter 429 Die kürzeste nützliche Interaktion ist eine Anfrage, die ihr Schlüssel-Budget überschreitet. Der Server gibt zurück: ```http HTTP/1.1 429 Too Many Requests Content-Type: application/json Retry-After: 12 X-RateLimit-Limit: 120 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1717000060 { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 12 seconds." } } ``` `Retry-After` ist das massgebliche Warten — schlaf mindestens so lange vor dem nächsten Versuch. `X-RateLimit-Reset` ist der Unix-Timestamp, an dem das Fenster nachfüllt. Der Code im Body ist `rate_limited`; Clients sollen auf den Code verzweigen, nicht die Message parsen. ## Standard-Limits | Oberfläche | Budget | Bucket | | -------------------------------- | --------------------------------- | ---------------- | | REST-API (`/api/v1/*`) | 120 Anfragen / Minute / Schlüssel | Token, Burst 200 | | OpenAI-kompatibler Chat | 30 Anfragen / Minute / Schlüssel | Token, Burst 50 | | OpenAI-kompatibles Model-Listing | 120 Anfragen / Minute / Schlüssel | Token, Burst 200 | | Workflow-Trigger-Webhooks | 60 Anfragen / Minute / Schlüssel | Token, Burst 100 | | Agent-Webhooks | 30 Anfragen / Minute / Schlüssel | Token, Burst 50 | | Datei-Upload | 50 Anfragen / Minute / Mitglied | Festes Fenster | | E-Mail-Versand | 100 Nachrichten / Stunde / Org | Token, Burst 120 | Token-Buckets erlauben einen kurzen Burst über die Rate hinaus — nützlich für Batch-Importe — und pegeln sich dann auf die nachhaltige Rate ein. Feste Fenster füllen an der Minuten-Grenze nach; eine Anfrage um 14:59:59 und eine um 15:00:00 passieren beide. Wähl die Buckets passend: ein UI, das einmal pro Minute mountet, liest als ein Token, nicht als 60 über ein Fenster. ## Org-Obergrenzen Tale Cloud legt eine weiche Obergrenze pro Org über die Schlüssel-Budgets, skaliert auf den Plan der Org. Die Obergrenze schützt gegen einen entlaufenen Schlüssel, indem sie verhindert, dass ein Client das gesamte Budget der Org verbraucht. Selbst gehostete Instanzen haben standardmässig keine Org-Obergrenze — die Schlüssel-Budgets oben sind der einzige Boden. Wenn du auf Cloud ein höheres Budget pro Schlüssel für eine bekannte Last brauchst, frag den Support mit dem Schlüssel-Namen und der erwarteten nachhaltigen Rate. Kapazitätszuteilungen gelten pro Schlüssel, nicht pro Org. ## Retry-Strategie Die richtige Strategie ist exponentielles Backoff mit Jitter, gedeckelt auf den `Retry-After`-Wert, wenn vorhanden: 1. Bei 429 lies `Retry-After` und schlaf mindestens so lange. 2. Wenn `Retry-After` fehlt (unüblich), starte bei 1 s und verdoppele bei jedem weiteren 429, gedeckelt bei 60 s. 3. Füg bis zu 25 % Jitter hinzu, damit parallele Clients nicht im Gleichschritt wiederholen. 4. Gib nach dem achten Versuch auf und melde den Fehler — der Bucket ist gesättigt, weitere Wiederholungen helfen nicht. Idempotenz zählt hier: jeder Schreib-Endpoint akzeptiert einen `Idempotency-Key`-Header. Setz einen stabilen Key pro logischer Operation, damit Retries nicht doppelt feuern, wenn die ursprüngliche Anfrage erfolgreich war, die Antwort aber verloren ging. Siehe [API-Referenz](/de/develop/api-reference) für das Idempotenz-Fenster. ## Wo das hingehört Rate-Limits sind, wie Tale verfügbar bleibt, wenn ein Client sich danebenbenimmt. Die [API-Referenz](/de/develop/api-reference) nennt den 429 im Error-Modell und verweist zurück hierher für die Regeln; die [Webhooks-Referenz](/de/develop/webhooks) deckt die passende Retry-Richtlinie für ausgehende Auslieferungen ab. Wenn dein Verkehr für die Defaults falsch geformt ist und eine Support-Zuteilung nicht reicht, ist der Reiter [Self-hosted](/de/self-hosted/overview) die andere Antwort — die Plattform selbst zu betreiben, hebt die Cloud-Obergrenzen auf. # WebDAV-API Source: https://tale.dev/docs/de/develop/webdav-api Tale exponiert den Dokumentenspeicher unter `/dav/<orgSlug>/` als lese- und schreibfähigen WebDAV-Class-2-Endpunkt (RFC 4918). Diese Seite ist die Protokoll-Referenz — die Wire-Level-Oberfläche, die ein Client-Implementierer oder ein Drittanbieter-Werkzeug zur Integration braucht. Für den Endbenutzer-Einrichtungsleitfaden und Per-Client-Anweisungen siehe [Plattform > Integrationen > WebDAV](/platform/integrations/webdav). ## URL-Schema ```text /dav/<orgSlug>/documents/<path> R/W aktiver Dokumentenbaum /dav/<orgSlug>/.trash/<path> R/O gelöschte Dokumente (Soft-Delete-Ansicht) /dav/<orgSlug>/ R/O Sammlung, die die zwei obigen enthält ``` Segmente sind URL-kodiert. Der Server lehnt Segmente mit `/`, `\`, NUL oder den relativen Namen `.` und `..` ab. Jedes Segment muss 1–255 Byte umfassen. Der `orgSlug` entspricht `[a-zA-Z0-9_-]{1,64}`. Die Trailing-Slash-Konvention folgt WebDAV: Sammlungen (Ordner) werden mit Trailing Slash referenziert, Ressourcen (Dateien) ohne. Viele Clients normalisieren das unterwegs; der Server akzeptiert beide Formen beim Lookup und gibt die kanonische Form in PROPFIND-Antworten aus. ## Authentifizierung Nur HTTP Basic. Das Feld Benutzername kann ein beliebiger nicht-leerer Wert sein — das App-Passwort ist die eigentliche Berechtigung, und der Server vergleicht den Benutzernamen nicht mit deinem Konto. Deine Tale-Konto-E-Mail einzutragen ist die Konvention für lesbare Audit-Logs, und die meisten Clients erwarten eine E-Mail-ähnliche Zeichenkette, aber die Auth-Entscheidung wird allein auf dem Passwort getroffen. Das Passwort ist ein **App-Passwort**, das du unter Einstellungen > WebDAV erzeugst. Dein Haupt-Konto-Passwort wird auf diesem Endpunkt nicht akzeptiert. ```http Authorization: Basic <base64(email-oder-beliebig:app-passwort)> ``` App-Passwörter werden mit HMAC-SHA256 unter dem Deployment-Secret `WEBDAV_APP_PASSWORD_HMAC_KEY` gehasht. Der Schlüssel wird vom Plattform-Entrypoint (Prod) und von `server.ts` (Dev) deterministisch aus `INSTANCE_SECRET` abgeleitet — Operatoren müssen ihn nicht manuell setzen; ein expliziter Wert in `.env` überschreibt jedoch den abgeleiteten. Der Lookup grenzt über die ersten vier Zeichen des Passworts ein (neben dem Hash gespeichert für indexierten Lookup) und verifiziert mit einem Konstant-Zeit-HMAC-Vergleich. Jede authentifizierte Anfrage prüft zusätzlich, dass der anfragende Benutzer aktives Mitglied der Organisation in der URL ist — eine veraltete Zeile (Mitgliedschaft nach App-Passwort-Ausgabe entfernt) wird mit `403` abgelehnt. `OPTIONS` ist die einzige Methode ohne Authentifizierung; Clients nutzen sie zur DAV-Capability-Prüfung vor der Anmeldung. ## Methoden | Methode | Verhalten | Auth | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | | OPTIONS | Capabilities ankündigen. Gibt `DAV: 1, 2`, `Allow: …` und `Microsoft-Server-WebDAV-Extensions: 1` für Windows-Kompatibilität zurück. | Anonym OK | | PROPFIND | Eine Ressource auflisten (Depth 0) oder die direkten Kinder einer Sammlung (Depth 1). Die emittierte Eigenschaftsliste ist unten dokumentiert. **Depth: infinity wird mit 403 abgelehnt**, um unbegrenzte Antworten zu verhindern. | Erforderlich | | PROPPATCH | Gibt 207-Erfolg pro Eigenschaft zurück, ohne Werte zu speichern. Dead Properties werden in v1 nicht persistiert; PROPPATCH gelingt optimistisch zur Client-Kompatibilität. | Erforderlich | | GET / HEAD | Den Dokument-Blob streamen. Setzt `Content-Type`, `Content-Length`, `ETag` und `Last-Modified`. GET auf eine Sammlung gibt 405 zurück. | Erforderlich | | PUT | Ein Dokument erstellen oder ersetzen. Neuer Blob im Convex-Speicher mit Content-Hash-Dedup; die Dokument-Zeile erhält `sourceProvider: "webdav"`. Gibt 201 beim Erstellen, 204 beim Überschreiben zurück. | Erforderlich | | DELETE | Ein Dokument soft-löschen (`lifecycleStatus: "trashed"`) oder einen Ordner (kaskadiert Trash auf enthaltene Dokumente, hard-löscht die Ordner-Zeilen). Gibt 204 zurück. | Erforderlich | | MKCOL | Einen Ordner unter einem bestehenden Eltern erstellen. Nur leerer Body. Gibt 201 zurück, 405 wenn das Ziel existiert oder 409 wenn der Eltern fehlt. | Erforderlich | | MOVE | Umbenennen oder verschieben. Atomar für Dokumente. Für Ordner wird die `parentId` des verschobenen Ordners aktualisiert. Beachtet `Overwrite: T/F` und `If`. Gibt 201 (neues Ziel) oder 204 (Überschreiben) zurück. | Erforderlich | | COPY | Serverseitige Kopie. Dokumentkopien wiederverwenden die Convex-Storage-ID (Dedup). Ordnerkopien rekursiv. Beachtet `Overwrite` und `If`. | Erforderlich | | LOCK | Class-2-exklusive oder geteilte Schreibsperre. Timeout aus `Timeout: Second-N`-Header, gedeckelt auf 3600. Refresh durch erneutes LOCK mit `If: (<opaquelocktoken:...>)` und leerem Body. | Erforderlich | | UNLOCK | Eine Sperre per Token freigeben. Nur der Sperr-Besitzer kann freigeben. Gibt 204 zurück. | Erforderlich | `HEAD` teilt seinen Handler mit `GET` ohne Body. ## Eigenschaften PROPFIND gibt diese Live-Eigenschaften für jede Ressource zurück: - `resourcetype` — `<collection/>` bei Ordnern, leer bei Dokumenten. - `displayname` — der Ordnername oder Dokumenttitel. - `getlastmodified` — RFC-1123-Zeitstempel. Dokumente nutzen `sourceModifiedAt` falls gesetzt, sonst die Erstellungszeit der Dokument-Zeile. - `creationdate` — ISO 8601 der Zeilen-Erstellungszeit. - `getcontenttype` — nur Dokumente; der MIME-Typ beim Upload. - `getcontentlength` — nur Dokumente; Bytes. - `getetag` — nur Dokumente; Content-Hash falls bekannt, sonst Dokument-ID. - `supportedlock` — bewirbt exklusive Schreibsperren. - `lockdiscovery` — vorhanden bei Ressourcen mit aktiven Sperren. Dead Properties werden nicht gespeichert. PROPPATCH gibt für eine allein gesetzte Dead Property 200 zurück, aber das Setzen einer Live-/geschützten Eigenschaft liefert pro Eigenschaft ein 403 (`cannot-modify-protected-property`), und alle Dead Properties derselben Anfrage werden dann als 424 Failed Dependency gemeldet (RFC 4918 §9.2 Atomarität). Es wird nie ein Wert persistiert. ## Sperrsemantik Sperren leben in ihrer eigenen Convex-Tabelle, gekeyt mit `(organizationId, resourcePath)`. Wire-Form ist `opaquelocktoken:<uuid>`. Der Server: - Deckelt Timeout auf 3600 Sekunden. Anfragen für längere Fenster werden still gekappt. - Behandelt `LOCK` mit `If: (<opaquelocktoken:UUID>)`-Header und leerem Body als Refresh — der Ablauf der bestehenden Sperre wird verlängert. - Gibt `412 Precondition Failed` beim Refresh zurück, wenn das gelieferte Token unbekannt ist. - Gibt `423 Locked` auf `PUT / DELETE / MOVE / COPY / MKCOL / PROPPATCH` gegen einen gesperrten Pfad zurück, wenn die Anfrage keinen passenden `If`-Header trägt. - Gibt `412 Precondition Failed` zurück, wenn das gelieferte `If`-Token nicht zur Live-Sperre passt. - Lässt Sperren faul ablaufen — die Lookup-Abfrage gibt null für abgelaufene Zeilen zurück und plant eine Fire-and-Forget-Löschung. - Hard-löscht jede unter einem App-Passwort gehaltene Sperre, wenn dieses App-Passwort widerrufen wird. `UNLOCK` erfordert sowohl einen gültigen `Lock-Token`-Header als auch, dass der anfragende Benutzer der Sperr-Besitzer ist. ## Statuscodes - `200` — OPTIONS, GET, HEAD, LOCK, LOCK-Refresh, PROPPATCH (pro Eigenschaft) - `201` — PUT erstellen, MKCOL, MOVE/COPY auf neues Ziel - `204` — DELETE, UNLOCK, PUT überschreiben, MOVE/COPY überschreiben - `207` — PROPFIND, PROPPATCH (Multi-Status-Hülle) - `400` — fehlerhafter `Destination` / `If` / `Lock-Token` / `Timeout`-Header - `401` — fehlende oder ungültige Basic-Auth - `403` — Depth: infinity abgelehnt; .trash-Schreibversuch; Root-Delete/Move; falscher App-Passwort-Besitzer bei UNLOCK; Benutzer kein Mitglied der Org; MOVE/COPY auf sich selbst oder in den eigenen Teilbaum; Cross-Org-`Destination` - `404` — Ressource nicht gefunden - `405` — GET auf eine Sammlung; PUT auf einen Sammlungs-Pfad; MKCOL auf existierendem Pfad; Root-MKCOL - `409` — MKCOL, MOVE oder COPY wenn das Ziel-Elternverzeichnis nicht existiert - `412` — `If`-Token-Mismatch; `If-Match` / `If-None-Match`-Vorbedingung fehlgeschlagen; MOVE/COPY mit `Overwrite: F` auf ein existierendes Ziel - `413` — PUT-Body über dem Größenlimit, oder ein XML-Request-Body (PROPFIND / PROPPATCH / MKCOL / LOCK) über 64 KB - `415` — MKCOL mit nicht-leerem XML-Body (extended MKCOL nicht implementiert) - `423` — Schreiben auf einem gesperrten Pfad ohne passendes `If` - `502` — Cross-Host-`Destination`; Storage-Proxy-Fetch fehlgeschlagen - `503` — LOCK-Anzahl-Limit für das App-Passwort überschritten (mit `Retry-After`) - `507` — Ordner-Teilbaum zu groß zum Löschen, Verschieben oder Kopieren in einer einzigen Anfrage ## Compliance - DAV Class **1** (Basis): vollständig. - DAV Class **2** (Sperren): vollständig, mit dem oben beschriebenen Lazy-Expiry-Verhalten. - DAV Class **3** (Kalender, Kontakte, Suche, ACL): nicht implementiert. Der Server bewirbt `DAV: 1, 2` in der OPTIONS-Antwort. ## Limits - `Depth: infinity` auf PROPFIND wird mit `403` abgelehnt. - `Timeout: Second-N` auf LOCK wird auf `[1, 3600]` begrenzt. - Die PUT-Body-Größe ist standardmäßig auf **5 GB** begrenzt (`413` bei Überschreitung), erzwungen sowohl am Reverse-Proxy als auch im Plattform-Server. Betreiber können das Limit über die Umgebungsvariable `WEBDAV_MAX_PUT_BYTES` anpassen. Der Body wird an eine Convex-Presigned-URL gestreamt, ohne dass ein großer Upload im Plattform-Speicher gepuffert wird. - XML-Request-Bodys (PROPFIND / PROPPATCH / MKCOL / LOCK) sind auf **64 KB** begrenzt (`413` bei Überschreitung) — diese Envelopes sind per Design winzig. - App-Passwörter werden mit HMAC-SHA256 gehasht; das Geheimnis taucht nach dem Create-Call in keiner Antwort mehr auf. - `lastUsedAt` wird höchstens einmal pro Minute pro App-Passwort gepatcht, um Write-Storms auf belebten Mounts zu vermeiden. ## Netzwerk-Voraussetzungen Der WebDAV-Endpunkt läuft im Plattform-Hono-Server (`platform:3000` in Compose). Caddy routet `/dav/*` über den Default-Fallback dorthin — keine Extra-Konfiguration erforderlich. Der Pfad erfordert, dass der Plattform-Server `ADMIN_KEY` in seiner Umgebung gesetzt hat, damit er interne Convex-Abfragen mit Admin-Auth aufrufen kann. Für Dev (`bun dev`) wird derselbe Dispatch als Vite-Middleware gemountet (`vite-plugins/serve-webdav.ts`) — `curl` und Clients können `http://localhost:3000/dav/<orgSlug>/...` gegen einen laufenden Dev-Server ohne Rebuild treffen. ## Sicherheit WebDAV schickt das App-Passwort als HTTP-Basic-Header bei jeder Anfrage — keine Session, kein Token-Refresh, einfach die nackte Berechtigung wiedergespielt bei jedem PROPFIND, PUT, LOCK und so weiter. Hänge den Endpunkt nur über HTTPS ein; über reines HTTP leakt das Passwort an jeden auf der Leitung, und ein Widerruf der Zeile ist die einzige Erholung. Stecke das App-Passwort niemals direkt in die URL (die `https://user:pass@host/...`-Kurzform) — die meisten Clients protokollieren URLs in Shell-History, Crash-Reports und Proxy-Access-Logs, wo die Berechtigung den Unmount weit überdauern würde. Lass den WebDAV-Client das Passwort im System-Schlüsselbund speichern (macOS Keychain, Windows Credential Manager, GNOME Keyring) und über den Standard-Credential-Prompt herausgeben. Der Server erzwingt TLS auf der Reverse-Proxy-Schicht in Produktion; der Dev-Modus über reines HTTP ist nur für `localhost`-Tests gedacht. Audit-Logs erfassen jede authentifizierte Anfrage mit dem Präfix des verwendeten Passworts, sodass eine geleakte Berechtigung sich nachverfolgen und widerrufen lässt, ohne die übrige Geräteflotte zu rotieren. ## Wo das hinpasst WebDAV ist die Mount-Protokoll-Oberfläche desselben Dokumentenspeichers, den die [REST-API-Referenz](/develop/api-reference) für Bulk-Import und Suche bedient — beide Wege schreiben in dieselbe Tabelle, aus der der [Dokumenten-Hub](/platform/knowledge/documents) liest, sodass eine über den Finder erstellte Datei ohne Sync-Schritt in der Web-Oberfläche erscheint. Das Protokoll ist die richtige Wahl, wenn Dokumente sich wie ein lokaler Ordner anfühlen sollen; die REST-API ist die richtige Wahl, wenn ein Skript oder Agent Byte-Kontrolle über das Geschriebene braucht. RFC 4918 ist die Wire-Level-Autorität für alles auf dieser Seite. # Status-Page Source: https://tale.dev/docs/de/develop/status-page Die Status-Page ist die kanonische Aufzeichnung der Verfügbarkeit von Tale Cloud. Jeder rotierbare Service hat seine eigene Status-Zeile, die Incident-Historie wird für den Audit-Pfad geführt, und die Seite ist der Kanal, den Tale während eines Incidents nutzt — bevor E-Mails rausgehen, bevor Support-Tickets beantwortet sind, wird die Seite aktualisiert. Lies das, wenn etwas sich seltsam verhält und du wissen willst, ob es nicht nur dich trifft. Abonnier den Feed, wenn du auf deiner Seite für die Integration verantwortlich bist — die Seite sagt dir, welcher Service degradiert ist, damit du den Alarm zum richtigen Team routen kannst, ohne die falsche Bereitschaft zu wecken. ## Ein durchgespieltes Abonnement Die Status-Page liegt unter `https://status.tale.dev`. Abonnieren ist eine URL: ```bash curl -sS https://status.tale.dev/history.rss ``` Der RSS-Feed trägt jeden Status-Wechsel — offen, Update, gelöst — für jeden Service. E-Mail-Abonnement ist dasselbe Ein-Klick-Formular auf der Seite; der E-Mail-Kanal liefert dieselben Events mit fünf Minuten Debounce. ## Umfang pro Service | Service | Was er abdeckt | Wann er rot wird | | ---------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | `platform` | Die TanStack-Start-+-Convex-Anwendung — Agents, Workflows, Integrations, UI. | UI nicht erreichbar; API gibt 5xx; Auth defekt. | | `rag` | Der Python-FastAPI-Dokumentdienst — Indexierung, Retrieval. | Dokument-Uploads stocken; Retrieval ist leer. | | `crawler` | Der Crawl4AI-Web-Extraktionsdienst — verwendet von Document-Ingest und Tavily-Fallback. | Web-gezogene Dokumente scheitern; Deep Research stockt. | | `proxy` | Der Caddy-Edge — TLS-Terminierung, HTTP-Routing. | Gesamter Tale-Cloud-Verkehr betroffen. | | `db` | TimescaleDB — dauerhafter Zustand für die Convex-Schicht und Plattform-Metadaten. | Schreiben abgelehnt; die platform-Zeile wird ebenfalls rot. | Jede Zeile trägt die letzten 90 Tage Uptime als Sparkline. Ein Incident liest sich als farbiges Band auf der Zeile; ein Klick aufs Band öffnet den Verlauf — erstes Update, Folge-Updates, Auflösung, Post-Mortem, wenn eines ansteht. ## Incident-Historie Die Historie wird unbefristet aufbewahrt. Jeder Incident hält die betroffenen Services fest, die Kundenwirkungs-Aussage, den Verlauf und das Post-Mortem, wenn der Incident die Schwere-Schwelle reisst, die eines verlangt. Die Schwelle steht auf der Seite selbst; die Faustregel ist alles mit Cross-Org-Kundenwirkung und einer Dauer über 30 Minuten. Die Seite gehört der Bereitschafts-Rotation. Updates werden vom Engineer geschoben, der die Seite hält, nicht von einem automatisierten System — die Wahl ist bewusst, weil die Seite auch das Dokument ist, das nach dem Vorfall zu Kunden und Auditoren geht. ## Self-hosted: was sich ändert Selbst gehostete Instanzen erscheinen nicht auf `status.tale.dev` — die Seite deckt Tale Cloud ab. Jedes Deployment bringt stattdessen seine eigene Status-Page mit, von der Plattform ausgeliefert und ohne Anmeldung erreichbar unter `https://<dein-host>/status`. Sie rendert serverseitig eine Gesundheits-Zusammenfassung — operational, degraded oder outage — aus einem Liveness-Probe gegen das Convex-Backend, sodass ein Betreiber (oder ein Endnutzer, der prüft, ob es nur bei ihm hakt) die Verfügbarkeit ohne Login lesen kann. Die maschinenlesbare Form ist `https://<dein-host>/status.json`, die dasselbe Ergebnis als JSON zurückgibt, das ein Uptime-Monitor pollen kann. Diese Seite meldet die Verfügbarkeit des Deployments selbst. Für tieferes Betriebssignal — Container-Gesundheit von `tale status`, Anfrage-Metriken aus den Caddy-Logs und Control-Plane-Events im In-Product-Audit-Log — bildet die [Observability-Troubleshooting-Seite](/de/self-hosted/operate/observability/troubleshooting) Symptome auf Logs ab. ## Wo das hingehört Die Status-Page ist der operative Kanal; [Vertrauen und Compliance](/de/cloud/trust-and-compliance) ist der Audit-Kanal und listet die Seite als Beleg für die Infrastruktur-Verfügbarkeits-Kontrolle. Wenn du Tale in eine Pipeline verdrahtest und die Integration auf einen Tale-Ausfall reagieren soll, ist der RSS-Feed der Eingang; wenn du das hier liest, weil gerade etwas in deiner Integration scheitert, listet die [API-Referenz](/de/develop/api-reference) die Error-Codes, auf die du verzweigen solltest. # Integrations Source: https://tale.dev/docs/de/develop/integrations Integrations sind die Nähte zwischen Tale und dem Rest deines Stacks. Der ausgelieferte Katalog deckt die üblichen SaaS-Systeme ab (Slack, GitHub, Microsoft 365, Google Drive, Shopify und den Rest); wenn dein Zielsystem nicht dabei ist, baust du die Brücke selbst. Drei Oberflächen erlauben das: ein JSON-deklarierter REST-Connector, ein SQL-Adapter für relationale Datenbanken oder ein MCP-Server, wenn ein selbst gehosteter Prozess die Aufrufe vermitteln soll. Lies das, wenn du den Integration-Katalog erweiterst. Komm zurück, wenn eine deklarierte Operation nicht im Agent-Toolbelt auftaucht — die Antwort ist fast immer ein Schema-Konflikt gegen das Reference unter `.tale/reference/integrations/`. ## Ein durchgespielter eigener REST-Connector Die kleinste nützliche Integration ist eine einzelne REST-Operation, deklariert in JSON. Leg einen Ordner ins Projekt und die Integration erscheint unter **Einstellungen > Integrations**, ohne Code-Änderung: ```text integrations/ acme-billing/ config.json connector.ts # optional, für nicht-triviale Request-Formung icon.svg ``` `config.json` deklariert die Auth-Methode, die erlaubten Hosts und die Operations: ```json { "slug": "acme-billing", "name": "ACME Billing", "auth": { "type": "apiKey", "header": "X-API-Key" }, "allowedHosts": ["api.acme.example.com"], "operations": [ { "name": "list_invoices", "method": "GET", "path": "/v1/invoices", "query": { "since": "string?" } } ] } ``` Die Operation taucht auf Agents als Tool-Familie auf, sobald die Org Credentials hinterlegt. Die Connector-Datei ist optional — greif darauf zurück, wenn die Response-Form geflacht werden muss oder Paginierungs-Schleifen nötig sind, die das Manifest nicht ausdrücken kann. Für einen OAuth2-Connector (`"auth": { "type": "oauth2", … }`) registriere Tales Callback-URL als erlaubte Redirect-URI in der Upstream-OAuth-App, sonst scheitert der Consent-Schritt mit einem `redirect_uri`-Mismatch. Der Callback ist `${SITE_URL}/api/integrations/oauth2/callback` (mit `BASE_PATH` vorangestellt, falls gesetzt). Für lokale Entwicklung ist dieser Origin deine Dev-URL — `http://localhost:3000/api/integrations/oauth2/callback`, kein `https://`-Host. ## Wahl der Oberfläche | Oberfläche | Greif darauf zurück, wenn | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | REST-Manifest | Das Zielsystem spricht JSON über HTTPS, und die Auth ist API-Schlüssel oder OAuth2. Deckt die meisten SaaS-APIs. | | SQL-Adapter | Das Ziel ist eine relationale Datenbank (Postgres, MySQL, SQL Server) und Agents sollen Tabellen unter Row-Level-Policy lesen. | | MCP-Server | Die Brücke muss ein langlebiger Prozess sein — lokale Dateien, eine eigene CLI, ein System, das aus dem Netz von Tale unerreichbar ist. | | Connector-TS | Das REST-Manifest deckt 80 % der API ab, aber eine Operation braucht Response-Formung, die das Manifest nicht deklarieren kann. | Die ausgelieferten Integrations unter [Platform > Integrations](/de/platform/integrations/overview) sind der Katalog der REST-Manifeste, die Tale ausliefert — lies ihre Configs in `builtin-configs/integrations/` für die Muster, die du kopierst. ## SQL-Adapter Ein SQL-Adapter exponiert eine Tale-geformte Tool-Oberfläche über eine SQL-Datenbank. Du deklarierst die Verbindung (Treiber, Host, Credential-Referenz) und die Tabellen, die die Integration lesen darf; der Adapter erzeugt eine `query_<table>`-Operation pro deklarierter Tabelle und eine `run_named_query`-Operation für die Queries, die du nach Namen freigibst. Schreibvorgänge gehen nur über deklarierte Mutations — es gibt keine rohe `execute`-Operation. Row-weise Autorisierung liegt beim Betreiber: deklarier eine Tenant-Spalte auf jeder Tabelle, und Tale injiziert den Tenant-Filter in jede erzeugte Query. Operations gegen Tabellen ohne Tenant-Spalte scheitern bei der Validierung zur Deploy-Zeit. ## MCP-Server Wenn die Integration sich nicht als JSON-Manifest ausdrücken lässt — eine CLI, eine lokale Toolchain, irgendetwas, das vom Tale-Netz isoliert ist — schreib einen MCP-Server und registrier ihn unter **Einstellungen > MCP-Server**. Jedes Tool, das der Server exponiert, erscheint im Agent-Toolbelt mit Per-Tool-Freigabe beim ersten Aufruf. Der Transport ist stdio für selbst gehostete Tale-Instanzen; für Tale Cloud lebt der Server in deinem Netz und Tale ruft ihn über einen signierten HTTPS-Tunnel auf. Der vollständige MCP-Walk-Through lebt unter [MCP-Server von Grund auf](/de/tutorials/developer/mcp-server-from-scratch) — diese Seite ist der Bau; die hier ist die Auswahl. ## Wo das hingehört Eigene Integrations sind, wie Tale Systeme erreicht, die der ausgelieferte Katalog nicht abdeckt. Die [Integrations-Übersicht](/de/platform/integrations/overview) listet, was schon da ist; sobald deine eigene Integration deklariert ist, erklärt [Agent-Tools](/de/platform/agents/tools), wie ihre Operations auf einem Agent auftauchen. Wenn die Brücke ganz ausserhalb von Tale leben muss — ein Prozess, den du startest, ein Host, den du kontrollierst — deckt die [MCP-Server-Referenz](/de/platform/integrations/mcp-servers) die andere Hälfte ab. # Webhooks Source: https://tale.dev/docs/de/develop/webhooks Webhooks sind, wie Tale und der Rest deines Stacks asynchron sprechen. Zwei Richtungen existieren: eingehend — dein System postet an einen Tale-Workflow-Trigger, um einen Lauf zu feuern — und ausgehend — Tale postet an deine URL, wenn etwas passiert, das es überwacht. Die zwei Hälften teilen sich das Auth-Modell (ein Bearer-Token), das Signier-Schema (HMAC-SHA256 über den Body) und die Retry-Richtlinie (exponentielles Backoff mit Jitter). Lies das, wenn du eine Integration verdrahtest, die in eine der Richtungen auf Events reagieren muss. Komm zurück, wenn ein Webhook feuert, der Empfänger ihn aber nicht sieht, oder wenn Retries sich nicht so verhalten, wie du es erwartet hast. ## Ein durchgespielter ausgehender Webhook Wenn ein Event, das Tale überwacht, geschieht — eine Workflow-Ausführung schliesst ab, ein Agent beendet eine Antwort, ein Dokument-Schreibvorgang ist fertig — postet Tale das Event an deine konfigurierte URL: ```http POST https://your-host.example.com/webhooks/tale Content-Type: application/json X-Tale-Event: workflow.execution.completed X-Tale-Signature: sha256=<hex> X-Tale-Delivery: <uuid> X-Tale-Timestamp: 1717000000 { "event": "workflow.execution.completed", "data": { "workflowId": "...", "executionId": "...", "status": "succeeded", ... } } ``` Verifiziere die Signatur, bevor du dem Body vertraust: HMAC-SHA256 über den rohen Body mit dem pro-Endpoint-Secret, hex-kodiert. Vergleiche in konstanter Zeit. Lehn jeden Request älter als fünf Minuten ab, indem du `X-Tale-Timestamp` gegen deine Uhr prüfst. ## Ein durchgespielter eingehender Trigger Wenn dein System einen Tale-Workflow feuern muss, poste an die Webhook-URL, die Tale erzeugt, sobald du dem Workflow einen Webhook-Trigger hinzufügst: ```bash curl -sS https://your-host.example.com/api/workflows/wh/<token> \ -H "Idempotency-Key: order-12345" \ -H "Content-Type: application/json" \ -d '{ "orderId": "12345", "amount": 199.0 }' ``` Das Token im URL-Pfad ist der Berechtigungsnachweis — ein Authorization-Header ist nicht nötig; behandle also die ganze URL als Secret und lösch den Webhook, um sie zu widerrufen. Der Body wird die Eingabe des ersten Workflow-Schritts. Ein frisches Annehmen gibt `{ "status": "accepted", "workflowSlug": "..." }` zurück; ein Replay mit demselben `Idempotency-Key` gibt statt eines neuen Laufs die `executionId` des früheren zurück. ## Signieren und verifizieren Ausgehend: das pro-Endpoint-Signier-Secret wird einmal angezeigt, wenn du den Endpoint unter **Einstellungen > Integrations** oder im Webhook-Trigger-Panel des Workflow-Editors hinzufügst. Tale signiert jeden Body mit HMAC-SHA256 mit diesem Secret; Verifizierung ist String-Vergleich in konstanter Zeit. Eingehend: es gibt kein Signieren — das Token in der URL ist die Auth. Kannst du die URL nicht geheim halten, gib sie nicht heraus; lösch den Webhook, um sie zu rotieren. ```python import hmac, hashlib def verify(body: bytes, signature: str, secret: str) -> bool: expected = "sha256=" + hmac.new( secret.encode(), body, hashlib.sha256, ).hexdigest() return hmac.compare_digest(expected, signature) ``` ## Idempotenz Eingehend: gib `Idempotency-Key` bei jedem Trigger-Aufruf mit. Tale speichert den Key gegen die resultierende Ausführung für 24 Stunden; ein Retry mit demselben Key gibt dieselbe Execution-ID zurück, ohne den Workflow erneut zu feuern. Ausgehend: jede Auslieferung trägt eine eindeutige `X-Tale-Delivery`-UUID. Nutz sie zum Dedupen auf deiner Seite — Tale wiederholt bei Nicht-2xx-Antworten, und dieselbe Delivery-UUID erscheint bei jedem Retry, bis der Empfänger bestätigt. ## Retries Ausgehende Retries folgen exponentiellem Backoff mit Jitter, begrenzt auf 24 Stunden an Versuchen. Der Plan: - Sofortiger Retry bei einem 5xx oder Timeout. - 30 s, 1 m, 5 m, 30 m, 2 h, 8 h, 24 h nach dem ersten Fehler. - Nach 24 h ohne 2xx ist die Auslieferung als fehlgeschlagen markiert; das Audit-Log hält es fest. Eingehende Retries sind die Verantwortung des Aufrufers — Tales Antwort zeigt Erfolg oder Fehler des Triggers, nicht der Workflow-Schritte. Willst du wiederholen, nutz einen stabilen Idempotenz-Key. ## Wo das hingehört Webhooks sind die Naht zwischen Tale und externen Systemen auf beiden Seiten. Die [API-Referenz](/de/develop/api-reference) behandelt die synchrone Hälfte — die Endpoints, die du aufrufst, wenn du einen Wert sofort zurück willst. Die [Trigger-Referenz](/de/platform/automations/triggers) deckt die Workflow-Seite eingehender Webhooks ab — die Konfiguration, die einen POST in einen Workflow-Lauf verwandelt. # AI-gestützte Entwicklung Source: https://tale.dev/docs/de/develop/ai-assisted-development Tale-Projekte sind JSON — Agents, Workflows, Integrations, Branding — und JSON lässt sich in AI-Editoren gut bearbeiten, wenn der Editor das Schema kennt. Die CLI legt dafür zwei Dinge an: eine Rules-Datei, die jeder Editor im Projekt-Root liest (`CLAUDE.md` für Claude Code, `.cursor/rules/tale.mdc` für Cursor, `.github/copilot-instructions.md` für Copilot, `.windsurfrules` für Windsurf), und einen schreibgeschützten Schema-Spiegel unter `.tale/reference/`, auf den die Rules-Datei den Editor verweist. Lies das, wenn du ein Tale-Projekt im AI-Editor bearbeiten willst, ohne JSON von Hand zu tippen. Komm zurück, wenn der Editor Felder erfindet oder die falsche Agent-Form verdrahtet — die Antwort ist fast immer, dass das Schema unter `.tale/reference/` veraltet ist. ## Ein durchgespieltes Setup Initialisier ein Projekt — die CLI schreibt die Rules-Datei und den Schema-Spiegel im selben Schritt: ```bash tale init my-org cd my-org ls -a # .cursor/ .github/ .tale/ .windsurfrules # CLAUDE.md agents/ workflows/ integrations/ branding/ ``` `CLAUDE.md` (gleichzeitig installiert als Cursor-`.mdc`, Copilot-`.md` und Windsurf-Rules) sagt dem Editor, wo er nachschlagen soll, bevor er eine Config bearbeitet: > Before creating or editing any config, read the relevant schemas and implementation code in `.tale/reference/` to understand the valid structure, fields, and constraints. Use existing config files in the project as examples. Die Direktive zählt, weil jeder Editor unter Last Schema-Reads überspringt, sofern nicht anders gesagt. Die Rules-Datei ist der Vertrag; der Schema-Spiegel ist die Wahrheit am Boden. ## Was wo liegt | Pfad | Was es ist | | ---------------------------------- | ----------------------------------------------------------------------------------- | | `agents/` | Eine JSON-Datei pro Agent — Anweisungen, Wissen, Tools, Modell. | | `workflows/` | Workflow-JSON-Configs, gruppiert nach Kategorie-Unterverzeichnis. | | `integrations/<slug>/config.json` | Integration-Manifest — Operations, Auth-Methode, erlaubte Hosts. | | `integrations/<slug>/connector.ts` | Optionaler TypeScript-Connector für REST-Formen, die das Manifest nicht abdeckt. | | `branding/branding.json` | Org-Branding — Farben, Logos, E-Mail-Absender. | | `.tale/reference/` | Schreibgeschützter Schema-Spiegel; neu erzeugt durch `tale init` und `tale update`. | Der Reference-Baum ist byte-identisch zu den Schemas, gegen die die Plattform beim Deploy validiert. Behandle ihn als kanonisch: wenn ein Feldname in einer handgeschriebenen Config dem Reference widerspricht, gewinnt das Reference. ## Arbeiten mit dem Editor Die Rules-Datei nennt drei Regeln, die jeder Editor beim Bearbeiten durchsetzt: - **Agents binden, delegieren, hängen an.** Ein Agent kann gleichzeitig Integrations binden (`integrationBindings`), an andere Agents delegieren (`delegates`) und Workflows anhängen (`workflows`). Lies bestehende Configs, bevor du eine neue Bindung einführst. - **Workflows nutzen Integration-Operations.** Ein Workflow-Schritt referenziert Integration-Operations, die in `integrations/<slug>/config.json` deklariert sind. Ein Schritt gegen eine nicht-existente Operation zu bearbeiten, lässt die Validierung scheitern. - **Benennung ist erzwungen.** Agent-Dateinamen matchen `[a-z0-9][a-z0-9_-]*\.json`. Workflow-Step-Slugs matchen `[a-z0-9][a-z0-9_-]*`. Integration-Verzeichnisse sind kleingeschrieben alphanumerisch mit Bindestrichen oder Unterstrichen. Wenn der Editor eine Änderung vorschlägt, frag ihn, welche Datei in `.tale/reference/` er zugrunde gelegt hat. Wenn er das nicht kann, erzeug den Spiegel mit `tale update` neu und versuch es nochmal. ## Cursor: Config-Ebene vs. Runtime-Ebene Cursor taucht in Tale an zwei getrennten Stellen auf — verwechsle sie nicht. | Ebene | Was sie tut | Wo sie lebt | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | **Config** | Hilft Cursor (oder einem anderen AI-Editor), Tale-Projekt-JSON auf deinem Rechner zu bearbeiten | `.cursor/rules/tale.mdc`, `CLAUDE.md`, `.tale/reference/` — alles, was `tale init` schreibt | | **Runtime** | Führt die Cursor Agent CLI headless in einer isolierten Sandbox aus, wenn du mit dem eingebauten **Cursor**-External-Agent chattest | Chat-Picker → **Cursor**; Agent-JSON mit `primaryBehavior: "external-agent"` und `agentKind: "cursor"` | Rules-Datei und Schema-Spiegel auf dieser Seite sind die **Config-Ebene**: Sie steuern einen lokalen Editor, während du Agents, Workflows und Integrations änderst. Die **Runtime-Ebene** ist ein verwalteter Sandbox-Turn — `agent -p --output-format stream-json` mit deinem `CURSOR_API_KEY`, normalisierter Fortschritt im Chat und Session-Resume über Follow-ups. Credentials, Modelle und Abrechnung für Runtime-Turns stehen in [External agents](/de/platform/agents/external-agent), nicht hier. ## Wo das hingehört AI-gestützte Entwicklung ist der Bearbeitungspfad; Deployment ist der Veröffentlichungspfad. Sobald eine Config die Editor-Validierung passiert, gleicht [`tale deploy`](/de/self-hosted/install/cli-install) sie gegen die Plattform ab — derselbe Schema-Check, diesmal als Schranke. Für Features, die der Editor nicht erreicht (der In-Product-Builder, der visuelle Workflow-Editor), ist der [Platform-Reiter](/de/platform) die kanonische Oberfläche; der AI-Editor-Pfad hier ist für Projekte, die Config-as-Code bevorzugen. # Contributor-Setup Source: https://tale.dev/docs/de/develop/contributor-setup Diese Seite ist für Contributors, die Tale aus dem Quellcode laufen lassen und eine Änderung zurückgeben wollen. Sie deckt die Voraussetzungen ab, das einmalige Setup, den Pre-flight-Check, der eine kaputte Maschine vor einem langen Boot erkennt, und was du von `bun run dev` erwarten kannst. Es ist nicht der Operator-Weg — willst du Tale benutzen statt verändern, installiert der [Self-hosted Quickstart](/de/self-hosted/install/quickstart) stattdessen den paketierten Stack mit der CLI. Der Quellcode ist ein einziger Bun-Workspace, von Anfang bis Ende — der ganze Stack ist TypeScript, ohne Python und ohne einen zweiten Paketmanager zu installieren. Ein einziges `bun install` verdrahtet jeden Dienst, und `bun run dev` bootet die Plattform mit einem lokalen Convex-Backend, generierten Dev-Secrets und Vite — kein Cloud-Konto, keine von Hand editierte `.env`. Die Wissens-Arbeit, die früher in eigenständigen Diensten lebte (RAG-Suche, Dokument-Ingestion, Web-Crawling, Dokumentgenerierung), läuft jetzt im Convex-Backend, also gibt es dafür nichts Zusätzliches zu starten. ## Ein funktionierendes Setup von Anfang bis Ende Der kürzeste Weg von einem frischen Klon zu einer laufenden App sind vier Befehle. Der Pre-flight-Check zwischen Install und Dev ist der, der dir ein verwirrendes Scheitern zehn Schichten tief erspart: ```bash bun install # jeden Workspace verdrahten bun run setup:check # Bun, die Dev-Ports und die Convex-CLI prüfen bun run dev # Convex + Vite booten (achte auf das READY-Banner) ``` Wenn `setup:check` durchweg grün ausgibt und `bun run dev` sein `READY`-Banner erreicht, ist deine Umgebung in Ordnung. Der Rest dieser Seite erklärt jedes Teil und was zu tun ist, wenn eines davon meckert. ## Voraussetzungen Nur ein Tool muss auf deinem `PATH` liegen, bevor irgendetwas anderes passiert, denn der ganze Stack ist TypeScript auf einer einzigen Laufzeit: - **Bun 1.3 oder höher** — die Workspace-Laufzeit und der Paketmanager. Installier es von [bun.sh](https://bun.sh/docs/installation) und bestätige mit `bun --version`. Alles andere, was der Quellcode braucht (die Convex-CLI, jede Dienst-Abhängigkeit), löst `bun install` auf. Für die lokale Entwicklung mit `bun run dev` brauchst du kein Docker — es spawnt Convex direkt auf deiner Maschine. Docker kommt nur für den containerisierten Hybrid-Modus weiter unten und für die Operator-Installation ins Spiel. ## Installation und Pre-flight Ein einziges Install deckt jeden Workspace ab, denn das Repo ist ein Bun-Workspace-Graph: ```bash bun install ``` Vor dem ersten `bun run dev` lauf den Pre-flight-Check. Er prüft deine Bun-Version, dass die Ports 3000 und 3210 frei sind und dass die Convex-CLI erreichbar ist — und gibt für alles Fehlende die exakte Korrektur aus, sodass du keine falsche Bun-Version mitten in einem Cold-Boot entdeckst: ```bash bun run setup:check ``` Jede fehlschlagende Zeile trägt ihre Korrektur: ein `bun upgrade` für ein altes Bun, ein `lsof`/`kill`-Paar für einen belegten Port. Ein sauberer Lauf endet mit Null und sagt dir, dass du mit `bun run dev` weitermachen kannst. ## Was `bun run dev` tut `bun run dev` ist der Entwicklungs-Orchestrator. Er lädt deine `.env`-Dateien, generiert unsichere lokale Defaults für jedes Secret, das du nicht gesetzt hast, spawnt ein lokales Convex-Backend im Anonymous-Modus, synct das Environment hinein, führt Convex-Codegen aus, wartet, bis die Auth-Routen antworten, und startet dann Vite. Die Plattform ist der langsamste Server beim Hochkommen, weil sie auf Convex wartet, also dauert ein Cold-Start 30 bis 90 Sekunden. Bis der Orchestrator sein `READY`-Banner ausgibt, ist es erwartet und kein Fehler, dass die App auf `http://localhost:3000` Verbindungen ablehnt — Vite hat den Port noch nicht gebunden. Siehst du das Banner, ist die App erreichbar und die Auth gesund. Stopp den ganzen Stack mit `Ctrl-C`; er fährt sowohl Convex als auch Vite sauber herunter. Der Dev-Orchestrator generiert alles, was er braucht, also ist eine lokale Kopie von `.env.example` für die lokale Entwicklung optional — die unsicheren Defaults (`INSTANCE_SECRET`, `BETTER_AUTH_SECRET`, der WebDAV-HMAC-Key) werden beim Boot gefüllt und als Warnungen ausgegeben. Setz echte Werte in `services/platform/.env.local` nur, wenn du produktionsförmiges Verhalten brauchst oder einen Default überschreiben willst. ## Wenn ein Port belegt ist `bun run dev` bindet zwei Ports: 3000 für die Vite-App und 3210 für das lokale Convex-Backend. Es scheitert sofort mit einer umsetzbaren Meldung, wenn einer belegt ist, denn ein stiller Fallback auf einen anderen Port würde den Convex-Proxy und jeden `localhost:3000`-Link brechen. Der übliche Verursacher ist ein vorheriges `bun run dev` oder `tale dev`, das nicht vollständig beendet wurde. Gib den Port frei und lauf erneut. Der Befehl, der den Halter findet und stoppt, ist derselbe, den `setup:check` und der Orchestrator vorschlagen: ```bash lsof -nP -iTCP:3000 -sTCP:LISTEN # die PID zeigen, die den App-Port hält kill <PID> # sie stoppen ``` Um die App stattdessen auf einem anderen Port laufen zu lassen, setz `PORT`: `PORT=3005 bun run dev`. Gerät das Convex-Deployment nach der automatischen Wartung in einen schlechten Zustand — veraltetes Schema nach abgebrochener Migration, korrupte lokale SQLite-Datei — siehe [Lokale Convex-Dev-Daten zurücksetzen](#lokale-convex-dev-daten-zurücksetzen) unten; lösch `.convex/local/` nicht beiläufig. ## Wartung des lokalen Convex-Speichers Jeder `convex dev`-Push legt ein neues Function-Bundle unter `services/platform/.convex/local/default/convex_local_storage/modules/` ab. Die Convex-CLI räumt alte Blobs lokal nie auf — nach Monaten täglicher Entwicklung können Zehntausende Dateien (10+ GB) entstehen, und Cold Starts scheitern im 30-Sekunden-Fenster der CLI. `bun run dev` führt Wartung automatisch aus, bevor Convex startet: - **Prune**, wenn der Modul-Speicher 1.500 Blobs oder 2 GB überschreitet — löscht nur unreferenzierte historische Function-Bundle-Blobs unter `convex_local_storage/modules/` und behält jedes Blob, das das aktuelle Deployment noch lädt (Modul-Source-Packages und ihre Node-`externalPackageId`-Deps-Parents, plus bis zu 1.000 neueste unreferenzierte Reste). SQLite-Datenbank, Uploads und Org-Konfig bleiben unberührt. Lassen sich die Live-Referenzen nicht lesen, oder wirken sie leer obwohl noch Blobs auf der Platte liegen, wird der Prune übersprungen statt zu raten. - **Integritätsprüfung** — fehlt ein Live-Modul-Blob schon auf der Platte, stoppt `bun run dev` mit einem klaren Fehler und verweist auf `setup:clean`. Weitermachen würde ein halb totes Backend starten (Chat und Crons scheitern mit undurchsichtigen Serverfehlern). - **Snapshot-Export-Artefakte löschen**, wenn die gecachte Convex-Backend-Version nicht mehr zur lokalen Deployment-Konfiguration passt — entfernt `export.zip` und Import/Export-Reste, die einen fehlgeschlagenen Re-Import auslösen können, ohne Dev-Daten zu löschen. Setz `TALE_DEV_SKIP_CONVEX_MAINTENANCE=1`, um Prune/Snapshot-Cleanup zu deaktivieren (die Integritätsprüfung läuft weiter). `bun run setup:check` warnt (nicht blockierend), wenn der Modul-Speicher den Prune-Schwellenwert schon überschreitet. ## Lokale Convex-Dev-Daten zurücksetzen Nur als letzter Ausweg — `bun run setup:clean` löscht **alle** lokalen Convex-Dev-Daten: jede Tabelle in der lokalen SQLite-Datei, jeden Upload in `convex_local_storage/files/` und jedes Function-Bundle. Org-Konfig auf der Platte und `.env.local` bleiben unberührt. **Behalte deine Daten über den Reset hinweg.** Selbst wenn das Integritäts-Gate anschlägt (ein Bundle eines Live-Moduls fehlt), startet das Backend selbst noch — du kannst deine Daten also vorher exportieren und danach wiederherstellen, und der Reset verliert nichts: ```bash # 1. Backend starten (umgeht das Integritäts-Gate von `bun run dev`), dann # in einem zweiten Terminal exportieren: bun run --filter @tale/platform convex:dev cd services/platform && npx convex export --path convex-backup.zip # 2. Zurücksetzen (abgesichert — siehe unten), frisches Deployment # bootstrappen, dann wiederherstellen: bun run setup:clean # tippe: delete local convex bun run dev # auf das READY-Banner warten cd services/platform && npx convex import --replace-all convex-backup.zip ``` `bun run setup:clean` ist absichtlich abgesichert (Coding-Agenten dürfen es nicht laufen lassen, es sei denn, du hast ausdrücklich darum gebeten): 1. Selbst im Terminal ausführen — nicht über einen Agenten. 2. Beim Prompt die exakte Phrase `delete local convex` tippen (ein bloßes `y` wird abgelehnt). 3. Nicht-interaktive Läufe (CI) brauchen `TALE_CONFIRM_DESTROY_LOCAL_CONVEX=delete-local-convex` — in Agent-Shells nie setzen. Probier zuerst automatische Wartung und normales `bun run dev`. Musst du doch zurücksetzen, **exportiere vorher** (siehe oben), um deine Daten zu behalten — lass den Export nur weg, wenn du die lokalen Conversations, Uploads und den übrigen Anonymous-Deployment-Zustand wirklich nicht brauchst. ## Hybrid-Modus gegen ein containerisiertes Convex `bun run dev` spawnt standardmäßig ein ephemeres Convex-Backend, was für die meiste Arbeit das Richtige ist. Willst du schnelle Vite-Reloads gegen ein stabiles Convex, das Produktion spiegelt, fahr den dedizierten `convex`-Container und richte Vite stattdessen auf ihn: ```bash docker compose up convex # ein Terminal: das stabile Backend CONVEX_EXTERNAL=true bun run dev # ein anderes: Vite gegen den Container ``` Setz `CONVEX_URL`, wenn dein Container Convex auf einem Nicht-Standard-Host oder -Port bereitstellt. Das ist der einzige lokale Dev-Weg, der Docker braucht, und er ist optional — das ephemere Default-Backend braucht nichts außer den drei Voraussetzungen. ## Bevor du einen PR öffnest Jeder PR läuft durch ein Gate: `bun run check`, also Format, Lint, Typecheck und die volle Testsuite über jeden berührten Workspace. Ein grüner Lauf ist das Merge-Signal; ein roter blockiert. Die Pre-PR-Checkliste in [`AGENTS.md`](https://github.com/tale-project/tale/blob/main/AGENTS.md) listet den Rest — Docs und Übersetzungen kommen im selben PR wie der Code, der sie geändert hat. Berührt deine Änderung `services/docs/`, lauf auch das Docs-Gate (`bun run --filter @tale/docs test`), damit strukturelle Parität, Terminologie und Prosa-Checks vor dem Review passen. Alles, was ein Nutzer sehen, konfigurieren oder aufrufen kann, braucht seine Docs in allen drei Basis-Locales im selben Commit aktualisiert. ## Wo das hingehört Contributor-Setup ist der Boden, auf dem jede andere Entwickler-Aufgabe steht: bring die Voraussetzungen an ihren Platz, lass `setup:check` die Maschine bestätigen, und `bun run dev` gibt dir die ganze Plattform mit einem lokalen Backend in unter zwei Minuten, sobald die Images warm sind. Der Pre-flight-Check und die Port-Korrektur existieren, weil die häufigsten First-Run-Fehler eine falsche Tool-Version oder ein zurückgebliebener Prozess sind, der einen Port hält — beides Fünf-Sekunden-Korrekturen, sobald du sie sehen kannst. Läuft der Stack erst, rahmt die [Develop-Übersicht](/de/develop/overview) die externe Oberfläche, gegen die du baust, und [KI-gestützte Entwicklung](/de/develop/ai-assisted-development) deckt das Nutzen von Tales eigenen Agents zum Schreiben von Tale-Konfigurationen ab. Trägst du eine Container-Änderung statt einer Quellcode-Änderung bei, ist [Mitwirken](/de/self-hosted/contributing-docker) unter dem Reiter Selbst gehostet der Build-and-Test-Spaziergang für diesen Weg. # Quickstart Source: https://tale.dev/docs/de/get-started/quickstart Das ist der kürzeste Weg zu einem funktionierenden Chat mit einem Agent: Instanz besorgen, anmelden, Nachricht senden, der Antwort beim Streamen zusehen. Auf einer bereiten Instanz dauert das rund fünf Minuten, auf deiner eigenen Maschine fünfzehn — und es endet mit dem Bildschirm unten, einer echten Antwort eines Agents über deinen Arbeitsbereich. <Frame caption="Wo dieser Quickstart endet: eine gestreamte Agent-Antwort im Chat."> ![Ein Chat-Verlauf mit einer Nutzerfrage zu Onboarding-Feedback und einer Assistenten-Antwort, die eine Markdown-Tabelle mit drei Themen enthält.](/images/platform/chat-thread-reply.webp) </Frame> ## Hol dir eine Instanz Beide Editionen sind dasselbe Produkt — entscheide danach, wer den Stack betreiben soll. <Tabs> <Tab title="Selbst gehostet"> Mit laufendem [Docker](https://www.docker.com/products/docker-desktop) stellen drei Befehle den ganzen Stack auf deiner Maschine auf: ```bash curl -fsSL https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.sh | bash tale init my-project && cd my-project tale dev ``` Der erste Lauf zieht die Images — rechne mit fünf bis zehn Minuten. Sobald der Browser aufgeht, registriere dich: Das erste Konto übernimmt die Rolle **Inhaber** und erstellt deine Organisation. Der [selbst gehostete Quickstart](/de/self-hosted/install/quickstart) erklärt jeden Schritt in der Tiefe, samt Windows und Fehlersuche. </Tab> <Tab title="Cloud"> Cloud-Instanzen werden für dich aufgesetzt: Füll das [Demo-Formular](https://tale.dev/de/request-demo) aus, und das Tale-Team stellt deine eigene Instanz bereit. Sobald sie steht, öffne sie und registriere dich — das Formular fragt nach Name, E-Mail und Passwort; bestätige den E-Mail-Link, sobald er ankommt, benenne deine Organisation, und du landest im Dashboard. Der Setup-Assistent bietet direkt an, einen KI-Anbieter zu verbinden — füge dort einen [OpenRouter](https://openrouter.ai)-Schlüssel ein, und der Chat funktioniert sofort. Der [Einstieg für Admins](/de/get-started/admins) geht denselben Assistenten mit Screenshots durch, wenn du mehr willst als den Happy Path. </Tab> </Tabs> ## Schick deine erste Nachricht <Steps> <Step title="Öffne einen neuen Chat"> Klicke in der Sidebar auf **Neuer Chat**. Der Composer am unteren Bildschirmrand ist der Ort, an dem alles beginnt: links die Agent-Auswahl, daneben die Modell-Auswahl und rechts das Nachrichtenfeld mit dem Senden-Knopf. Wartet der Composer mit vorausgewähltem **Assistent** und **Auto**, bist du bereit zu senden. <Frame caption="Der Composer — oben das Nachrichtenfeld, darunter die Agent- und die Modell-Auswahl und der Senden-Knopf."> ![Der leere Chat-Composer, dessen Platzhalter zu einer Frage nach Kontakten, Produkten oder Dokumenten einlädt, über einer Werkzeugleiste mit den Knöpfen für Anhang und Prompt-Bibliothek, der Agent- und der Modell-Auswahl sowie den Knöpfen für Stummschaltung, Mikrofon und Senden.](/images/platform/chat-composer.webp) </Frame> </Step> <Step title="Stell eine echte Frage"> Lass den Agent auf **Assistent** und das Modell auf **Auto** — Tale ermittelt zum Zeitpunkt der Anfrage das beste verfügbare Modell. Tippe eine Frage und sende sie. Die Antwort streamt Token für Token herein; wenn der Agent vor dem Antworten nachdenkt, erscheint über der Antwort eine aufklappbare Denk-Zeile. <Check> Eine gestreamte Antwort, die deine Frage beantwortet, heißt: Die ganze Kette funktioniert — Anbieter, Modell-Routing und Agent. Du hast einen funktionierenden Arbeitsbereich. </Check> </Step> </Steps> ## Wo du jetzt stehst Du hast eine laufende Instanz und einen Agent, der antwortet. Die nächsten fünfzehn Minuten hängen von deiner Rolle ab: Der [Einstieg für Mitglieder](/de/get-started/members) behandelt Dokumente und Projekte, der [Einstieg für Redakteure](/de/get-started/editors) veröffentlicht deinen ersten Spezialisten-Agent, der [Einstieg für Admins](/de/get-started/admins) richtet Team und Anbieter ein, und der [Einstieg für Entwickler](/de/get-started/developers) bringt dir einen API-Schlüssel und deine erste Anfrage. # Dein erster Tag als Arbeitsbereichs-Verantwortlicher Source: https://tale.dev/docs/de/get-started/admins Dieser Einstieg ist für die Person, die den Arbeitsbereich verantwortet. In fünfzehn Minuten erstellst du die Organisation, verbindest den Anbieter, der den Chat zum Antworten bringt, holst die ersten Teammitglieder an Bord und lernst, wo die Governance-Steuerung wohnt, bevor du sie brauchst. Du brauchst ein Konto auf einer laufenden Instanz ([Quickstart](/de/get-started/quickstart)); auf einer brandneuen Instanz ist das erste Konto automatisch **Inhaber**, und diese Rolle trägt jede Berechtigung unten. <Steps> <Step title="Erstelle den Arbeitsbereich"> Kommst du aus dem Quickstart, existiert deine Organisation schon — spring zum Anbieter-Schritt. Eine frische Anmeldung ohne Organisation landet im Erstellungsassistenten: Der **Organisationsname** ist der Anzeigename, den dein Team in der Ecke jeder Seite sieht — wähl einen, der ein Rebranding überlebt. Der Assistent bietet danach an, einen KI-Anbieter zu verbinden, und endet im Dashboard. <Frame caption="Der Arbeitsbereichs-Schritt des Erstellungsassistenten."> ![Der Assistent zum Erstellen einer Organisation auf seinem Arbeitsbereichs-Schritt, mit Northlight Labs im Feld Organisationsname und aktivem Knopf Weiter.](/images/get-started/org-create-wizard.webp) </Frame> </Step> <Step title="Verbinde einen KI-Anbieter"> Nichts antwortet, solange kein Anbieter verbunden ist. Hast du den Anbieter-Schritt des Assistenten übersprungen, öffne **Einstellungen > KI-Anbieter** und klicke auf **Anbieter hinzufügen** — füg einen [OpenRouter](https://openrouter.ai)-Schlüssel ein für den breitesten Modellkatalog, oder einen beliebigen OpenAI-kompatiblen Anbieter. Eine Bestätigung auf der Anbieterzeile heißt: Der Schlüssel validiert; ab diesem Moment kann jeder Agent im Arbeitsbereich antworten. <Frame caption="Ein verbundener Anbieter mit seinem Modellkatalog."> ![Die Einstellungsseite für KI-Anbieter listet einen verbundenen Anbieter, OpenRouter, mit seiner Basis-URL und 52 Modellen.](/images/get-started/settings-providers.webp) </Frame> </Step> <Step title="Hol das Team an Bord"> Um Personen hinzuzufügen, öffne **Einstellungen > Organisation**, scroll zum Abschnitt **Mitglieder** und klicke auf **Mitglied hinzufügen**. Jede Person landet mit einer Rolle, die absteckt, was sie tun kann: **Mitglied** liest und chattet, **Redakteur** baut Agents und Wissen, **Entwickler** verdrahtet Workflows, Automatisierungen und API-Zugriff, **Admin** betreibt den Arbeitsbereich. Fang niedrig an — eine Rolle später anzuheben ist ein Klick, geleakten Zugriff einzufangen nicht. <Frame caption="Der Abschnitt Mitglieder — jedes Konto und seine Rolle."> ![Die Organisationseinstellungen mit dem Abschnitt Mitglieder, der den Arbeitsbereichs-Inhaber Alex Rivera listet, und dem Knopf Mitglied hinzufügen.](/images/get-started/settings-organization-members.webp) </Frame> <Check> Ein Teammitglied, das sich anmeldet und im Chat eine Antwort bekommt, beweist die ganze Kette — Konto, Rolle, Anbieter — ohne dass du danebenstehst. </Check> </Step> <Step title="Wisse, wo Governance wohnt"> Am ersten Tag brauchst du keine Richtlinien, aber du solltest die Tür kennen: **Einstellungen > Richtlinien** hält Audit-Logs, Nutzungsanalysen, Inhaltsrichtlinien, Guardrails und Aufbewahrung. Die eine Gewohnheit, die sich heute schon lohnt: Überflieg nach der ersten Woche die [Audit-Logs](/de/platform/admin/governance/audit-logs) — sie zeigen dir, was dein Arbeitsbereich tatsächlich tut. </Step> </Steps> ## Wo du jetzt stehst Der Arbeitsbereich steht: Ein Anbieter antwortet, das Team ist mit abgesteckten Rollen drin, und du kennst die Orte der Steuerung. Die vollständige Berechtigungsmatrix sind [Mitglieder und Rollen](/de/platform/admin/members-and-roles); die [Admin-Übersicht](/de/platform/admin/overview) verzeichnet jeden Bereich, den du jetzt verantwortest; und wenn die Compliance fragt, ist [Governance](/de/platform/admin/governance/audit-logs) der Abschnitt, den du ihr zeigst. # Dein erster Tag als Agent-Autor Source: https://tale.dev/docs/de/get-started/editors Dieser Einstieg ist für die Person, die aus „das Team stellt immer dieselben Fragen“ einen Agent macht, der sie beantwortet. In fünfzehn Minuten erstellst du einen Agent, formst sein Verhalten und siehst ihm im Chat beim Antworten zu — die Schleife, die jeder spätere Agent verfeinert. Du brauchst die Rolle **Redakteur** oder höher (der Bereich Agenten ist für Mitglieder ausgeblendet) in einem Arbeitsbereich, in dem der Chat bereits antwortet — das ist der [Quickstart](/de/get-started/quickstart). <Steps> <Step title="Erstelle den Agent"> Für einen Agent, den Teammitglieder im Chat auswählen können, öffne **Agenten** in der Sidebar und klicke auf **Agent erstellen**. Benenne ihn nach dem Job, nicht nach der Technologie — „Support-Triage“ schlägt „GPT-Helfer“ —, denn der Name ist das, was Teammitglieder später im Composer auswählen. </Step> <Step title="Gib ihm eine Identität"> Der Editor öffnet auf dem Tab **Allgemein**: der Anzeigename, den Teammitglieder sehen, eine einzeilige Beschreibung und der Agent-Typ. Der Schalter, der am ersten Tag zählt, ist **Im Chat sichtbar** — ohne ihn existiert der Agent zwar, aber niemand kann ihn im Composer auswählen. <Frame caption="Der Tab Allgemein — Identität, Agent-Typ und Chat-Sichtbarkeit."> ![Der Tab Allgemein im Agent-Editor für den Assistenten-Agent mit den Agent-Typ-Optionen, dem Schalter Im Chat sichtbar und dem Feld für den Anzeigenamen.](/images/get-started/agent-editor-general.webp) </Frame> </Step> <Step title="Schreib die Anweisungen"> Öffne **Anweisungen & Modelle** — der Hebel, der am meisten bewegt. Schreib einen Absatz, als würdest du eine neue Kollegin briefen: die Stimme, in der er antwortet, die Domäne, die er verantwortet, und die Fälle, die er ablehnen soll. Konkret schlägt vollständig — du verfeinerst, sobald du echte Antworten gesehen hast. <Frame caption="Anweisungen & Modelle — der System-Prompt über der geordneten Modellliste."> ![Der Tab Anweisungen & Modelle im Agent-Editor mit dem Feld für den System-Prompt und der geordneten Modellliste für den Assistenten-Agent.](/images/platform/agent-editor-instructions.webp) </Frame> </Step> <Step title="Binde das Modell"> Derselbe Tab bindet das Modell: Wähl eines aus den konfigurierten Anbietern des Arbeitsbereichs, oder lass das Routing auf automatisch, damit Tale pro Anfrage das beste verfügbare Modell ermittelt. Klicke auf **Speichern** — ein Toast **Agent gespeichert** bestätigt den Schreibvorgang. </Step> <Step title="Sieh ihm beim Antworten zu"> Öffne **Neuer Chat**, wähl deinen Agent in der Agent-Auswahl und frag etwas, das klar in deinen Anweisungen liegt. Frag danach etwas, das die Anweisungen ablehnen sollen. <Frame caption="Die Agent-Auswahl — dein neuer Agent gelistet neben den Katalog-Agents."> ![Die geöffnete Agent-Auswahl des Chat-Composers, die die im Arbeitsbereich verfügbaren Agents listet.](/images/platform/chat-agent-picker.webp) </Frame> <Check> Eine Antwort in der richtigen Stimme auf die erste Nachricht und eine Ablehnung auf die zweite heißt: Die Anweisungen greifen — der Agent ist echt. </Check> </Step> </Steps> ## Wo du jetzt stehst Du hast den kleinsten echten Agent ausgeliefert: Anweisungen, ein Modell, ein Platz in der Auswahl. Das vollständige Modell hinter dem, was du angefasst hast, sind die [Agent-Konzepte](/de/platform/agents/concepts) — Anweisungen, Wissen, Tools und Modell als vier Knöpfe. Der natürliche nächste Bau ist [dein erster Agent von Anfang bis Ende](/de/tutorials/editor/first-agent-end-to-end), der Wissensanbindungen und eine echte Domäne ergänzt; danach führen [Agents mit Wissen](/de/tutorials/editor/agent-with-knowledge) und [Delegation zwischen Agents](/de/tutorials/editor/delegate-between-agents) dieselbe Schleife weiter. # Dein erster Tag mit Tale Source: https://tale.dev/docs/de/get-started/members Dieser Einstieg ist für alle, die Tale nutzen, statt es zu konfigurieren. In fünfzehn Minuten chattest du mit einem Agent, fügst ein Dokument hinzu, aus dem der ganze Arbeitsbereich schöpfen kann, und lernst, wo gemeinsame Arbeit lebt — die drei Handgriffe, die die meisten Tage abdecken. Du brauchst ein angemeldetes Konto in einem Arbeitsbereich, in dem der Chat bereits antwortet — das ist der [Quickstart](/de/get-started/quickstart). Chatten und Stöbern funktionieren mit der Rolle **Mitglied**; die zwei Schreib-Handgriffe unten (ein Dokument hochladen, eine Aufgabe verschieben) brauchen **Redakteur** oder höher — fehlt dir ein Knopf, ist das die Rollengrenze, kein kaputter Arbeitsbereich. <Steps> <Step title="Chatte mit einem Agent"> Deine erste Nachricht hast du schon im Quickstart geschickt — diesmal sieh zu, was der Agent daraus macht. Klicke auf **Neuer Chat**, frag etwas aus deiner echten Arbeit und klapp die Tool-Aufruf-Boxen über der Antwort auf: Sie zeigen, was der Agent gelesen oder ausgeführt hat, bevor er antwortete. Um eine Datei an eine einzelne Konversation zu hängen, füg sie per Paste ein, zieh sie in den Composer oder nutze das Anhang-Steuerelement — der Agent liest sie nur für diesen Chat. [Anhänge](/de/platform/chat/attachments) beschreibt, was akzeptiert wird. </Step> <Step title="Gib dem Arbeitsbereich ein Dokument"> Chat-Anhänge verschwinden mit der Konversation; Wissen bleibt. Soll ein Dokument jedem Agent und jedem Teammitglied zur Verfügung stehen, öffne **Wissen > Dokumente** und klicke auf **Dokumente hochladen**, dann **Von deinem Gerät**, wähl die Datei und klicke auf **Hochladen**. Das Dokument erscheint in der Tabelle und wird im Hintergrund indiziert — sobald es indiziert ist, zitieren Agents es in ihren Antworten. Das Upload-Menü erscheint ab Redakteur; mit der Rolle Mitglied liest und durchsuchst du die Bibliothek und gibst die Datei einem Redakteur zum Hinzufügen. <Frame caption="Die Dokumente-Tabelle nach ein paar Uploads."> ![Die Dokumente-Tabelle im Bereich Wissen mit drei hochgeladenen Textdateien und ihrem Indizierungsstatus.](/images/get-started/documents-list.webp) </Frame> <Check> Stell in einem neuen Chat eine Frage, die nur dein Dokument beantworten kann. Eine Antwort, die das Dokument zitiert, beweist den Index von Anfang bis Ende. </Check> </Step> <Step title="Finde die Arbeit des Teams in Projekten"> Öffne **Projekte** in der Sidebar. Ein Projekt bündelt alles zu einem Vorhaben — Aufgaben auf einem Board, geteilte Dateien, Projekt-Chats und eigene Agents. Öffne ein Projekt und wechsle auf dem Tab **Aufgaben** zwischen **Board** und **Liste**; mit Bearbeitungszugriff (ab Redakteur) ziehst du eine Aufgabe zwischen den Spalten, um ihren Status zu ändern — bleibt die Karte nach einem Neuladen in ihrer neuen Spalte, ist die Änderung für alle gespeichert. <Frame caption="Das Aufgaben-Board eines Projekts — zieh Karten zwischen den Spalten."> ![Ein Projekt-Aufgabenboard mit dem Titel Website-Relaunch und sieben Aufgabenkarten, ein bis zwei je Spalte, verteilt über Backlog, Zu erledigen, In Bearbeitung, In Prüfung, Erledigt und Abgebrochen.](/images/platform/projects-task-board.webp) </Frame> </Step> <Step title="Finde zurück zu deinen Chats"> Chats verschwinden nie stillschweigend. Klicke über dem Composer auf **Verlauf anzeigen**, um die Verlaufs-Sidebar zu öffnen — jeder Chat, den du in diesem Arbeitsbereich fortsetzen kannst, der neueste zuerst. Benennst du einen Chat um, behält er diesen Titel dauerhaft; löschst du einen, wandert er in den Papierkorb des Arbeitsbereichs, statt zerstört zu werden. </Step> </Steps> ## Wo du jetzt stehst Du kannst chatten, den Arbeitsbereich mit Wissen füttern und dich in gemeinsamer Arbeit bewegen — die tägliche Schleife eines Mitglieds. Als Nächstes lohnen sich [Chat-Grundlagen](/de/platform/chat/basics) für das mentale Modell hinter dem Composer und [Projekte nutzen](/de/tutorials/member/use-projects) für einen tieferen Projekt-Walkthrough. Sobald du bereit bist, einen eigenen Agent zu bauen, wechsle zum [Einstieg für Redakteure](/de/get-started/editors). # Dein erster Tag mit der Tale-API Source: https://tale.dev/docs/de/get-started/developers Dieser Einstieg ist für die Person, die Tale mit anderen Systemen verdrahtet. In zehn Minuten erstellst du einen API-Schlüssel, machst deine erste authentifizierte Anfrage und weißt, an welche Tür du für Chat, Workflows und Dokumente klopfst. Du brauchst die Rolle **Entwickler** oder höher (darunter sind die API-Einstellungen ausgeblendet) auf einer laufenden Instanz — der [Quickstart](/de/get-started/quickstart) hilft, wenn du keine hast. Ersetze unten `your-host.example.com` durch den Host deiner Instanz. <Steps> <Step title="Erstelle einen API-Schlüssel"> Für einen Berechtigungsnachweis, den deine Skripte halten können, öffne **Einstellungen > API > REST** und klicke auf **API-Schlüssel erstellen**. Benenne ihn nach dem System, das ihn nutzen wird — Schlüssel werden nach Namen gelistet, und in einem Jahr schlägt „zapier-bridge“ jedes „test“. Der Schlüsselwert erscheint genau einmal, bei der Erstellung; leg ihn in deinen Secret-Manager, nicht in den Code. <Frame caption="Die REST-API-Einstellungen — Schlüssel werden hier erstellt und widerrufen."> ![Die Einstellungsseite für REST-API-Schlüssel listet zwei Schlüssel — Production ingest und CI pipeline —, jeder nur mit seinem Schlüssel-Präfix, dem Datum unter Hinzugefügt und der Markierung Nie verwendet, neben dem Knopf API-Schlüssel erstellen.](/images/get-started/settings-api-keys.webp) </Frame> </Step> <Step title="Mach die erste Anfrage"> Der kürzeste nützliche Aufruf listet die Agents, die dein Schlüssel sehen kann. Der Schlüssel reist als Bearer-Token mit; den Arbeitsbereichs-Kontext leitet Tale aus dem Schlüssel selbst ab: ```bash curl -sS https://your-host.example.com/api/v1/agents \ -H "Authorization: Bearer $TALE_API_KEY" ``` <Check> Ein JSON-Array von Agents — samt dem eingebauten Assistenten — beweist Schlüssel, Header und Route. Ein `401` heißt: Der Token-Header ist fehlerhaft, oder der Schlüssel wurde widerrufen. </Check> </Step> </Steps> ## Der Rest der Oberfläche Alles Weitere sind Variationen dieser Anfrage. Die OpenAI-kompatiblen Endpunkte (`/api/v1/chat/completions`, `/api/v1/models`) bedeuten: Bestehende SDKs funktionieren, sobald du die Basis-URL tauschst. Workflows laufen per Slug über `/api/v1/workflows/<slug>/run` mit demselben Bearer-Schlüssel — oder werden von außen über Webhook-URLs der Form `/api/workflows/wh/<token>` gefeuert; das Token in der URL ist der Berechtigungsnachweis. Dokumente laden über `/api/v1/documents` hoch. Die [API-Referenz](/de/develop/api-reference) ist das vollständige Inventar mit Auth, Datenformen und Limits. ## Wo du jetzt stehst Du hältst einen funktionierenden Berechtigungsnachweis und hast die Anfrageform gesehen, die jeder Endpunkt teilt. Von hier aus macht [Tale aus einem Skript aufrufen](/de/tutorials/developer/call-tale-from-a-script) aus dem curl eine echte Integration, [einen Workflow per Webhook auslösen](/de/tutorials/developer/trigger-automation-via-webhook) behandelt die Push-Richtung, und [Webhooks](/de/develop/webhooks) dokumentiert die Payloads, die Tale dir sendet. # Tutorials Source: https://tale.dev/docs/de/tutorials/overview Tutorials sind Walkthroughs von Anfang bis Ende: Jedes bringt eine frische Instanz von „Ich möchte X tun" zu einem funktionierenden, verifizierten Ergebnis. Vorausgesetzt werden die passende Rolle und ein laufender Arbeitsbereich; die Konzept-Seiten unter [Plattform](/de/platform) erklären das mentale Modell, die Tutorials zeigen den Mechanismus von vorne bis hinten. Bist du noch keinen [Einstieg](/de/get-started/quickstart) durchgegangen, fang dort an — die Tutorials bauen auf den Handgriffen des ersten Tages auf, die dort abgedeckt sind. ## Wähl nach Rolle <CardGroup cols="2"> <Card title="Mitglieder-Tutorials" icon="message-circle" href="/de/tutorials/member/chat-effectively"> Effektiv chatten, in Projekten arbeiten, Sprach-Konversationen führen. </Card> <Card title="Redakteurs-Tutorials" icon="bot" href="/de/tutorials/editor/first-agent-end-to-end"> Einen ersten Agent von Anfang bis Ende bauen, Wissen anbinden, zwischen Agents delegieren, Workflows mit Genehmigungen ausliefern. </Card> <Card title="Entwickler-Tutorials" icon="terminal" href="/de/tutorials/developer/call-tale-from-a-script"> Tale aus einem Skript aufrufen, Workflows per Webhook auslösen, eigene Tools bauen, einen MCP-Server aufsetzen. </Card> <Card title="Verwaltungs-Tutorials" icon="shield" href="/de/tutorials/admin/office-add-in"> Das Office-Add-in installieren, Meeting-Transkription verdrahten, einen lokalen Anbieter verbinden. </Card> </CardGroup> ## Wo das hingehört Tutorials zitieren die Feature-Referenzen unter [Plattform](/de/platform) für das konzeptuelle Gerüst; sobald du eines durchgegangen bist, lohnt sich die zugehörige Konzept-Seite als zweite Lektüre. Weißt du nicht, welches Tutorial du wählen sollst: [Deinen ersten Agent bauen](/de/tutorials/editor/first-agent-end-to-end) ist das, was einem „Hallo Welt" für das Produkt am nächsten kommt — die meisten Produktfähigkeiten, die du später anfasst, tauchen dort schon auf. # Projekte nutzen, um Dateien und Chats zu bündeln Source: https://tale.dev/docs/de/tutorials/member/use-projects Ein Projekt ist das, wozu du greifst, wenn du dich zum zweiten Mal beim Einkopieren desselben Kontexts in einen Chat ertappst. Es bündelt Dateien, Instruktionen und Chats rund um eine Arbeitssache — einen Kunden, einen Launch, eine lange Untersuchung — damit jede neue Konversation mit bereits geladenem Kontext beginnt. Dieser Spaziergang führt ein frisches Projekt von „ich lade immer dasselbe Briefing erneut hoch" zu „jeder Chat in diesem Projekt kennt das Briefing schon" auf einer Instanz. Du brauchst eine Member-Rolle (das Minimum, um Projekte zu erstellen) und drei oder vier Dateien, auf die du immer wieder verweist. Die konzeptuelle Seite lebt in [Projekt-Konzepte](/de/platform/projects/concepts); dieser Spaziergang ist der End-to-End-Mechanismus. ## Bevor du beginnst Bestätige zwei Dinge. Deine Rolle ist mindestens Member — das Anlegen von Projekten ist auf Member und höher begrenzt. Du hast drei bis vier Dateien, die in deinen bisherigen Chats wiederkehren — ein Briefing, ein Transkript, eine Preisliste, eine Richtlinie. Die werden zum Arbeits-Set des Projekts. ## Schritt 1 — Das Projekt erstellen Das Projekt ist der Behälter, in dem die restlichen Teile leben. Öffne **Projekte > Neues Projekt** und setze: - **Name** — `Acme-Account` (oder was die Arbeitssache benennt) - **Beschreibung** — ein Satz, wofür das Projekt da ist - **Mitglieder** — vorerst privat lassen; du kannst Teammitglieder ergänzen, sobald der erste Chat funktioniert Speichern. Das Projekt erscheint in der Sidebar; ein Klick öffnet eine leere Projekt-Ansicht mit Tabs für Wissen, Threads, Agenten und Instruktionen. ## Schritt 2 — Die Dateien einmalig hochladen Die Projektdateien sind für jeden Chat im Projekt sichtbar, also passiert dieser Upload einmal und zahlt sich bei jedem späteren Chat aus. Öffne den **Wissen**-Tab und zieh die drei oder vier Dateien aus den Voraussetzungen hinein. Jede Datei landet im Projekt-Speicher und indexiert sich genauso wie ein Wissensdatenbank-Dokument. Sobald der Status **Bereit** ist, erreicht jeder im Projekt gestartete Chat die Dateien. ## Schritt 3 — Projekt-Instruktionen hinzufügen Projekt-Instruktionen rahmen jeden Chat im Projekt. Sie komponieren mit den eigenen Instruktionen des Agenten: das Projekt rahmt die Arbeit, der Agent rahmt die Antwort. Öffne den **Instruktionen**-Tab und setze: `You are working on the Acme account. The contract and the call notes in the Knowledge tab are the source of truth; cite them when you make a claim. The customer's voice is conservative — drafts should not promise dates we have not confirmed.` Speichern. Jeder neue Chat im Projekt läuft jetzt mit dieser Präambel zusätzlich zu den eigenen Instruktionen des Agenten. ## Schritt 4 — Einen Chat starten und prüfen, dass der Kontext mitgeht Öffne den **Threads**-Tab und klick **Neuer Chat**. Wähl einen Agent — der Default-Assistant reicht für den ersten Lauf — und stell eine Frage, die eine der Projektdateien beantwortet (`What does the contract say about the renewal clause?`). Die Antwort sollte den Vertrag zitieren; das Zitat öffnet die Datei aus dem Wissen-Tab des Projekts, nicht aus der Org-weiten Bibliothek. Antwortet der Agent ohne Zitat, wurden die Projektdateien nicht retrieved — meist weil der gewählte Agent kein Retrieval-Tool aktiviert hat. Wechsle auf einen Agent mit aktivem RAG oder aktivier es am Assistant für den Projektgebrauch. ## Wo das eingesetzt wird Ein Projekt mit Dateien, Instruktionen und Threads ist die kleinste nützliche Einheit von geteiltem Kontext in Tale. Dieselbe Form skaliert — Mitglieder ergänzen, damit ein Team das Projekt gemeinsam bearbeitet, einen projekt-skopierten Agent ergänzen, damit die Stimme festsitzt, das Projekt archivieren, wenn die Arbeit ausgeliefert ist. Für das tiefere Modell, was ein Projekt ist und wann man danach greift, siehe [Projekt-Konzepte](/de/platform/projects/concepts). Für projekt-skopierte Agenten siehe [Projekt-Agenten](/de/platform/projects/project-agents). # Effektiv chatten Source: https://tale.dev/docs/de/tutorials/member/chat-effectively Effektives Chatten in Tale dreht sich nicht um clevere Prompts; es dreht sich darum, dem Chat genug Kontext zu geben, damit das Modell deine Absicht beim ersten Lesen erfasst. Fünf kleine Gewohnheiten — den richtigen Agent wählen, das richtige Modell wählen, nur Wichtiges anhängen, im Scope fragen, die Zitate lesen — drehen die durchschnittliche Antwort von „danke für die Textwand" zu „genau, was ich brauchte". Diese Seite läuft die Gewohnheiten der Reihe nach in einem frischen Chat ab. Du brauchst eine Member-Rolle (das Minimum für Chat) und einen veröffentlichten Agent in der Org, den du ansprechen kannst. Die konzeptuelle Seite lebt in [Chat-Grundlagen](/de/platform/chat/basics); dieser Spaziergang ist der Alltags-Mechanismus. ## Gewohnheit 1 — Den Agent vor der ersten Nachricht wählen Der Agent ist der Hebel mit dem höchsten Ertrag pro Klick. Der Default-Assistant ist eine leere Leinwand; ein Agent mit gebundenem Wissen, aktiven Tools und justierter Stimme schlägt ihn bei jeder nicht-generischen Frage. Öffne den Agent-Picker im Composer und wähl den Agent, dessen Scope zu deiner Frage passt — Support, Sales, Research — bevor du tippst. Passt kein Agent, lass den Assistant an; greif nicht zu einem schief sitzenden Agent für „passt schon ungefähr". Ein schief sitzender Agent verweigert oft oder weicht vom gebundenen Wissen ab. ## Gewohnheit 2 — Das Modell zur Nachricht passend wählen Der Modell-Picker neben dem Agent-Picker listet die für den Agent erlaubten Modelle. **Auto** reicht meistens; wechsle, wenn die Nachricht ihre Form ändert. Eine lange Reasoning-Frage will ein grösseres Modell; ein schneller Lookup will ein kleineres, schnelleres. Eine Nachricht mit Bild braucht ein Vision-fähiges Modell — ohne dieses fällt das Bild stillschweigend weg. Der Modell-Picker zeigt den Tag (`Chat`, `Vision`, `Image`, `Embedding`) neben jedem Namen; pass den Tag zur Nachricht. ## Gewohnheit 3 — Nur anhängen, was der Agent braucht Anhänge laden zur Übernutzung ein. Ein 200-Seiten-PDF als einzelner Anhang füllt das Kontext-Budget und verdünnt die Antwort; die relevanten Seiten in den Prompt exzerpiert schlagen die ganze Datei. Hängst du ein langes Dokument doch an, stell eine spezifische Frage dagegen („was steht auf Seite 12 zu Rückerstattungen?") statt einer offenen („erzähl mir alles"). Für Dateien, auf die du oft verweisen wirst — eine Preisliste, ein Richtlinien-Dokument — lad sie in den [Wissen](/de/platform/knowledge/documents)-Bereich und binde sie an einen Agent. Einmal gebunden, hat jeder Chat mit diesem Agent sie verfügbar, ohne erneutes Hochladen. ## Gewohnheit 4 — Innerhalb des Scopes des Agenten fragen Jeder Agent hat einen impliziten Scope aus seinen Instruktionen und seinem gebundenen Wissen. Einen Billing-Agent zu Marketing-Strategie zu fragen, bringt im besten Fall eine höfliche Verweigerung, im schlimmsten eine Halluzination. Der billige Fix: lies die Bio des Agenten oben im Picker, bevor du fragst — sie benennt den Scope. Liegt deine Frage ausserhalb, wechsle den Agent. ## Gewohnheit 5 — Die Zitate lesen und ihnen folgen Enthält die Antwort Zitate (die kleinen inline Links), öffne eines. Das Zitat zeigt auf das Chunk der Quelle, aus dem der Agent zitiert hat; das Lesen bestätigt, dass der Agent nicht über das hinaus paraphrasiert hat, was die Quelle wirklich sagt. Die Zwei-Minuten-Gewohnheit, pro Antwort ein Zitat zu öffnen, fängt die kleine Teilmenge der Antworten ab, bei denen der Agent übergriffig war. ## Wo das eingesetzt wird Fünf Gewohnheiten, ein Chat, dieselbe Schleife jedes Mal, wenn du den Chat-Tab öffnest. Die Gewohnheiten verstärken sich — der richtige Agent macht das richtige Modell offensichtlich; das richtige Modell macht die Zitate vertrauenswürdig; die Zitate schliessen die Schleife. Für die Oberfläche, auf der diese Gewohnheiten leben, siehe [Chat-Grundlagen](/de/platform/chat/basics). Für die Datei-Seite — was wortwörtlich eingefügt wird, was indexiert wird — siehe [Anhänge](/de/platform/chat/attachments). # Ein eigenes Tool bauen Source: https://tale.dev/docs/de/tutorials/developer/build-a-custom-tool Ein eigenes Tool ist eine Funktion, die du schreibst und die das Modell eines Agenten beim Namen aufruft. Du deklarierst das Input-Schema und die Rückgabe-Form; Tale kümmert sich um die Serialisierung, die Tool-Call-Karte im Chat und das Zurückreichen des Resultats an das Modell. Dieser Spaziergang führt ein frisches eigenes Tool von „ich habe eine Funktion im Kopf" zu „der Agent ruft sie aus einem Chat heraus auf" auf einer einzigen Instanz. Du brauchst eine Developer-Rolle in der Org und Zugriff aufs Panel **Einstellungen > Eigene Tools**; alles andere passiert in der UI. Das zugrundeliegende Konzept lebt in [Agent-Tools](/de/platform/agents/tools); diese Seite richtet sich auf die Entwickler-Seite — Schemas, Transport, Fehler. ## Bevor du beginnst Bestätige zwei Dinge. Erstens: deine Rolle ist mindestens Developer — darunter ist das Panel versteckt. Zweitens: du hast einen Agent, den du bearbeiten kannst; falls nicht, erstelle einen über [Agent erstellen](/de/platform/agents/create), bevor du weitermachst. Der Spaziergang nutzt ein Tool mit einem Input und einem Output namens `lookup_order`, das eine Order-ID nimmt und einen Status-String zurückgibt — die kleinste Form, die das Schema, den Aufruf und das Rendern des Resultats übt. ## Schritt 1 — Das Tool in „Eigene Tools" definieren Der erste Zug ist das Registrieren von Tool-Name und JSON-Schema. Das Schema ist das, was das Modell sieht; ohne Schema hat das Modell keine Idee, welche Argumente es ausgeben soll, und der Aufruf passiert nie. Öffne **Einstellungen > Eigene Tools** und klick **Neues Tool**. Gib ihm einen Namen (`lookup_order`), eine Ein-Satz-Beschreibung (`Look up the status of an order by ID`) und ein JSON-Schema für den Input: ```json { "type": "object", "properties": { "orderId": { "type": "string", "description": "The order ID, e.g. ORD-12345" } }, "required": ["orderId"] } ``` Speichern. Das Tool ist nun in der Tool-Registry der Org registriert; noch nutzt es kein Agent. ## Schritt 2 — Die Implementierung verdrahten Ein registriertes Tool ohne Implementierung gibt dem Modell einen Fehler zurück. Tale bietet zwei Implementierungs-Modi: ein Inline-Sandbox-Skript (Python oder JavaScript, in Tales Sandbox ausgeführt) und einen ausgehenden HTTPS-Call (Tale POSTet die Argumente an deinen Endpoint, du gibst JSON zurück). Wähl für diesen Spaziergang den HTTPS-Modus — das ist die Form, zu der du in Produktion greifst. Im Detail-Panel des Tools setze: - **Endpoint-URL** — `https://your-api.example.com/lookup-order` - **Methode** — `POST` - **Auth-Kopfzeile** — ein Bearer-Token aus deinem Secret-Manager Tale POSTet `{ "orderId": "..." }` an deinen Endpoint; dein Endpoint gibt `{ "status": "shipped", "carrier": "DHL", "eta": "2026-06-01" }` zurück. Speichern. Das eigene Tool ist verdrahtet. ## Schritt 3 — Das Tool an einen Agent hängen Ein verdrahtetes Tool ist für Agenten unsichtbar, bis einer von ihnen die Erlaubnis bekommt, es aufzurufen. Öffne den Agent, den du erweitern willst, klick **Tools**, scroll zu **Eigene Tools** und schalte `lookup_order` ein. Speicher den Agent. Öffne einen Chat mit dem Agent und frag „what is the status of order ORD-12345". Der Chat zeigt zwischen deiner Nachricht und der Antwort eine eingeklappte `lookup_order`-Tool-Call-Karte; sie auszuklappen zeigt die Argumente, die das Modell ausgegeben hat (`{ "orderId": "ORD-12345" }`) und das JSON, das dein Endpoint zurückgegeben hat. Das Modell schreibt die Antwort dann mit dem Tool-Resultat. ## Wo das eingesetzt wird Ein eigenes Tool ist die Naht zwischen einem Agent und deiner Domäne — Order-Lookup, interne Suche, Rechner, alles, was eine Standard-Integration nicht abdeckt. Das Schema ist das, womit das Modell entscheidet, ob es aufruft — investier die Zeit für eine knappe Beschreibung und nimm nur die Felder, die du brauchst. Für Tools, die du Org-übergreifend teilen willst, siehe [MCP-Server von Grund auf](/de/tutorials/developer/mcp-server-from-scratch) — MCP ist das Protokoll für „ein Tool, viele Tale-Instanzen". Für die konzeptuelle Seite, was Tools in einem Agent tun, siehe [Agent-Tools](/de/platform/agents/tools). # Tale aus einem Skript aufrufen Source: https://tale.dev/docs/de/tutorials/developer/call-tale-from-a-script Tale aus einem Skript aufzurufen ist der Pfad, zu dem du greifst, wenn du einen Wert von einem Agent oder einem Workflow zurück willst, ohne die UI zu öffnen. Die Tale-API spricht JSON über HTTPS und akzeptiert ein Bearer-Token in der `Authorization`-Kopfzeile; von dort an ist jede Endpoint-Gruppe ein normaler REST-Call. Dieser Spaziergang führt dich von „ich will Tale skripten" zu einer in dein Terminal gestreamten Antwort in einer Sitzung. Du brauchst eine Developer-Rolle (um API-Schlüssel zu erzeugen), die URL deiner Tale-Instanz und eine Shell mit `curl`, Python oder Node. Die volle API-Oberfläche lebt in der [API-Referenz](/de/develop/api-reference); diese Seite ist der kürzeste End-to-End-Spaziergang dadurch. ## Bevor du beginnst Bestätige drei Dinge. Deine Instanz ist über HTTPS erreichbar — öffne `https://your-host.example.com` und prüf, dass das Dashboard lädt. Deine Rolle ist mindestens Developer — der Eintrag **Einstellungen > API-Schlüssel** ist für Member und Editor versteckt. Du hast mindestens einen veröffentlichten Agent — das Listen der Agenten gibt auf einer brandneuen Instanz ein leeres Array zurück, was den Rauch-Test mehrdeutig macht. ## Schritt 1 — Einen API-Schlüssel erzeugen Der erste Zug ist, einen API-Schlüssel zu erstellen, der auf deinen Nutzer skopiert ist. Der Schlüssel ist das, was jeder Skript-Call mitführt; ohne ihn gibt die API 401 zurück, und du kannst den Schlüssel nach der Erstellung nicht mehr lesen. Öffne **Einstellungen > API-Schlüssel** und klick **Neuer Schlüssel**. Gib ihm einen Namen (`local-script-test`), wähl einen Ablauf und klick **Erstellen**. Kopier den Schlüssel, den das Panel zeigt — Tale zeigt ihn einmal und nie wieder. Leg ihn für den Rest des Spaziergangs als Environment-Variable ab: ```bash export TALE_API_KEY="tk_..." export TALE_BASE_URL="https://your-host.example.com" ``` Der Schlüssel erbt deine Rolle; behandle ihn wie ein Passwort. ## Schritt 2 — Rauchtest mit curl Der kleinste End-to-End-Check ist das Listen der für deinen Schlüssel sichtbaren Agenten. Klappt das, sind Auth, Netzwerk und API in Ordnung; bricht es ab, sagt der Fehler-Modus, welches Stück kaputt ist. ```bash curl -sS "$TALE_BASE_URL/api/v1/agents" \ -H "Authorization: Bearer $TALE_API_KEY" \ -H "Accept: application/json" | jq ``` Eine 200 mit einem JSON-Body wie `{ "agents": [ ... ] }` bestätigt den Round-trip. Eine 401 heisst, der Schlüssel ist falsch; eine 403 heisst, der Schlüssel ist gültig, die Rolle aber zu niedrig; alles andere heisst, die Instanz ist nicht erreichbar oder der Pfad ist falsch. Pick eine Agent-ID aus der Antwort — du brauchst sie für Schritt 3. ## Schritt 3 — Einen Agent aus Python oder Node aufrufen Das Listen der Agenten ist read-only; die nützliche Arbeit passiert, wenn du einen Agent um eine Antwort bittest. Der OpenAI-kompatible Endpoint ist der einfachste Einstieg, weil bestehende SDKs unverändert laufen: ```python from openai import OpenAI import os client = OpenAI( base_url=f"{os.environ['TALE_BASE_URL']}/api/v1", api_key=os.environ["TALE_API_KEY"], ) reply = client.chat.completions.create( model="agt_your_agent_id_here", messages=[{"role": "user", "content": "Summarise the last quarter's revenue."}], ) print(reply.choices[0].message.content) ``` Das Feld `model` ist die ID des Agenten; die Instruktionen, das Wissen und die Tools des Agenten laufen wie konfiguriert. Dieselbe Form in Node nutzt `openai` aus npm mit derselben `baseURL` und demselben `apiKey`. Streaming geht mit `stream=True` und Server-Sent Events. ## Wo das eingesetzt wird Ein Skript ist der Pfad, den du nimmst, wenn die Daten-Ebene JSON ist, kein Bildschirm — Cronjobs, CI-Checks, interne Portale. Der API-Schlüssel führt deine Rolle, der OpenAI-kompatible Endpoint ist die reibungsärmste Form, und jeder List-Endpoint gibt denselben `{ resource: [...] }`-Umschlag zurück. Für eingehende Trigger — dein System POSTet in einen Tale-Workflow — siehe [Einen Workflow per Webhook auslösen](/de/tutorials/developer/trigger-automation-via-webhook). Für die volle Endpoint-Liste und das Fehler-Modell ist die [API-Referenz](/de/develop/api-reference) die einzige Quelle der Wahrheit. # Einen MCP-Server von Grund auf hochziehen Source: https://tale.dev/docs/de/tutorials/developer/mcp-server-from-scratch Ein Model-Context-Protocol-Server (MCP-Server) ist ein Prozess, der eine Liste von Tools über ein kleines JSON-RPC-Protokoll bereitstellt. Tale registriert einen MCP-Server einmal auf Org-Ebene; ab dann kann jeder Agent, der diesen Server in seinem Tools-Tab führt, dessen Tools aufrufen. Dieser Spaziergang führt einen brandneuen MCP-Server von „leerem Repo" zu „aus einem Chat von einem Agent aufgerufen" auf einer Tale-Instanz. Du brauchst eine Developer-Rolle, einen Host, der den MCP-Server laufen lassen kann (dein Laptop reicht für den Spaziergang; für Produktion ein Managed-Service oder Container) und eine HTTPS-URL, die Tale erreicht. Cloud-Orgs erreichen öffentliche URLs standardmässig; selbst gehostete Instanzen brauchen Netzwerk-Zugang dorthin, wo der MCP-Server läuft. ## Bevor du beginnst Bestätige zwei Dinge. Du hast Node 20 oder Python 3.11 installiert — die offiziellen MCP-SDKs zielen auf diese Laufzeiten. Die Tale-Instanz erreicht die URL deines MCP-Servers — für lokale Entwicklung tut's ein `ngrok`-Tunnel oder Äquivalent; für Produktion host den Server irgendwo mit einem stabilen HTTPS-Endpoint. Die konzeptuelle Seite von MCP in Tale lebt in [Agent-Tools](/de/platform/agents/tools); dieser Spaziergang ist die Verdrahtung. ## Schritt 1 — Den Server gerüstartig anlegen Der erste Zug ist, den minimalen MCP-Server zu generieren — ein Tool, ein Handler. Das offizielle SDK erledigt die Protokoll-Klempnerei, damit du nur das Tool schreibst. ```bash npm create mcp-server@latest hello-tale cd hello-tale ``` Öffne `src/index.ts` und ersetz das Beispiel-Tool durch eines, das die aktuelle Zeit in einer benannten Zeitzone zurückgibt: ```ts server.tool( 'current_time', 'Return the current time in a given timezone', { timezone: z.string() }, async ({ timezone }) => { const now = new Date().toLocaleString('en-US', { timeZone: timezone }); return { content: [{ type: 'text', text: now }] }; }, ); ``` Lass den Server lokal laufen: ```bash npm run start ``` Der Server lauscht standardmässig auf `http://localhost:3000/mcp`. Das Gerüst steht; in Tale weiss noch nichts davon. ## Schritt 2 — Auf HTTPS verfügbar machen MCP-Server, die Tale aufrufen kann, brauchen eine HTTPS-URL mit gültigem Zertifikat. Für lokale Entwicklung: einen `ngrok`-Tunnel auf Port 3000 zeigen lassen und die öffentliche URL kopieren, die der Tunnel ausgibt. Für Produktion host den Server hinter deinem normalen Ingress — Caddy, Nginx, eine Managed Function, alles, was TLS terminiert. Verifiziere, dass die öffentliche URL auf einen Health-Check antwortet: ```bash curl -sS "https://abcd.ngrok.app/mcp/health" ``` Eine 200 bestätigt Erreichbarkeit. Eine 502 oder ein Timeout heisst, der Tunnel leitet nicht weiter; starte ihn neu oder check die Firewall. ## Schritt 3 — Den Server in Tale registrieren Ein erreichbarer MCP-Server ist für Tale unsichtbar, bis du ihn registrierst. Öffne **Einstellungen > Integrationen > MCP-Server** und klick **Neuer Server**. Füll aus: - **Name** — `Hello Tale time` - **URL** — die öffentliche HTTPS-URL aus Schritt 2 (z.B. `https://abcd.ngrok.app/mcp`) - **Auth** — Bearer-Token, falls dein Server eines verlangt, fürs Spaziergang keines Klick **Speichern**. Tale ruft die Methode `list_tools` des Servers auf, um den Tool-Bestand zu entdecken; das Panel zeigt `current_time` mit Beschreibung. Der Server ist nun org-weit registriert. ## Schritt 4 — Den Server an einen Agent hängen und das Tool aufrufen Ein registrierter Server ist nur erreichbar für Agenten, die sich anmelden. Öffne einen beliebigen Agent, klick **Tools > MCP**, schalte **Hello Tale time** ein und speicher. Öffne einen Chat mit dem Agent und frag „what time is it in Tokyo right now". Der Chat rendert eine `current_time`-Tool-Call-Karte; sie auszuklappen zeigt `{ "timezone": "Asia/Tokyo" }` und den Zeitstempel, den dein Server zurückgegeben hat, und die Antwort des Agenten nutzt den Zeitstempel. ## Wo das eingesetzt wird Ein MCP-Server ist die richtige Form, wenn ein Tool ausserhalb von Tale leben muss — Code, der deinem Team gehört, ein Dienst in einem anderen Netz, eine Drittanbieter-API, die du umschnürst. Eigene Tools aus [Ein eigenes Tool bauen](/de/tutorials/developer/build-a-custom-tool) sind die richtige Form, wenn das Tool einmalig ist und in den Einstellungen einer Org lebt. Fürs grössere Bild, wie Tools erweitern, was ein Agent kann, siehe [Agent-Tools](/de/platform/agents/tools). Für die Verdrahtung einer Integration, die statt eigenem Code eine Drittanbieter-API umschliesst, ist [Integrationen-Überblick](/de/platform/integrations/overview) die nächste Lektüre. # Einen Workflow per Webhook auslösen Source: https://tale.dev/docs/de/tutorials/developer/trigger-automation-via-webhook Ein Webhook-Trigger macht aus einem Tale-Workflow etwas, das ein externes System per POSTen von JSON auslöst. Tale verifiziert das Bearer-Token, speichert den Idempotenz-Schlüssel, startet einen Lauf und gibt eine Execution-ID zurück — dieselbe Form, die jeder eingehende Webhook braucht, um wiederholungssicher zu sein. Dieser Spaziergang führt einen neuen Workflow von „ich will ihn von aussen feuern" zu „ein Order-Event POSTet und der Workflow läuft" auf einer Instanz. Du brauchst eine Developer-Rolle in der Org, einen vorhandenen Workflow (oder den leeren Starter) und eine Shell mit `curl`. Der volle Webhook-Vertrag — Signierung, Idempotenz, Wiederholungen — lebt in [Webhooks](/de/develop/webhooks); dieser Spaziergang ist die kleinste End-to-End-Nutzung der eingehenden Seite. ## Bevor du beginnst Bestätige zwei Dinge. Der Workflow, den du auslöst, existiert und ist veröffentlicht — Entwürfe lassen sich nicht triggern. Deine Rolle ist mindestens Developer — Trigger-Schlüssel zu erzeugen ist auf Developer und höher beschränkt. Hast du noch keinen Workflow, ist der kanonisch kleine „log das Payload in den Execution-Record"; erstell ihn über [Workflow mit Genehmigungen](/de/tutorials/editor/workflow-with-approvals) und entferne den Genehmigungs-Schritt für diesen Spaziergang. ## Schritt 1 — Einen Webhook-Trigger an den Workflow binden Der erste Zug ist, einen Webhook-Trigger an den Workflow zu binden. Ohne Trigger lässt sich der Workflow nur aus der UI aufrufen; mit einem bekommt er eine URL, an die jedes System POSTen kann. Öffne den Tab **Trigger** des Workflows und klick auf **Webhook hinzufügen**. Tale erzeugt eine eindeutige **Webhook-URL**, in deren Pfad der Berechtigungsnachweis als Token eingebettet ist — es gibt keinen separaten Schlüssel und keinen Authorization-Header. Speichere die URL, solange sie angezeigt wird: Wer sie hält, kann den Workflow feuern; behandle also die ganze URL als Secret. Den Webhook zu löschen widerruft sie. ```bash export TALE_TRIGGER_URL="https://your-host.example.com/api/workflows/wh/<token>" ``` ## Schritt 2 — Ein Payload per curl POSTen Die Webhook-URL ist ein normaler POST-Endpoint. Der Body wird zum Input des ersten Schritts des Workflows; die Kopfzeile `Idempotency-Key` macht Wiederholungen sicher — ein Replay gibt den früheren Lauf zurück, statt einen neuen zu starten. ```bash curl -sS "$TALE_TRIGGER_URL" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: order-12345" \ -d '{ "orderId": "12345", "amount": 199.0 }' ``` Eine 200 gibt `{ "status": "accepted", "workflowSlug": "..." }` zurück. Der Workflow läuft jetzt asynchron; öffne den Tab **Ausführungen** des Workflows und du solltest einen laufenden Run mit deinem Payload als Trigger-Input sehen. Eine 401 heißt, der Schlüssel ist falsch; eine 404 heißt, der Trigger-Name in der URL passt zu keinem veröffentlichten Workflow; eine 422 heißt, der Workflow ist archiviert oder der Trigger deaktiviert. ## Schritt 3 — Wiederholungen mit Idempotenz absichern Externe Systeme wiederholen bei Timeouts und 5xx-Fehlern; ohne Idempotenz feuert eine Wiederholung den Workflow doppelt. Die Kopfzeile `Idempotency-Key` aus Schritt 2 ist die Lösung: Tale speichert den Schlüssel 24 Stunden und gibt bei jeder Wiederholung mit demselben Schlüssel die ursprüngliche Execution zurück. Test das, indem du dieselbe curl-Anfrage oben erneut laufen lässt. Die Antwort trägt dieselbe `executionId` wie der erste Call, und der Tab **Ausführungen** zeigt weiterhin einen Lauf. Ändere den Schlüssel auf `order-12346` und curl erneut — der feuert einen zweiten Lauf. Das Quell-System muss pro logischem Event einen stabilen, deterministischen Schlüssel verwenden. Ein verbreitetes Muster ist `<event-type>-<event-id>`; nutze nie eine zur Wiederholungszeit generierte zufällige UUID, sonst erzeugt jede Wiederholung einen neuen Lauf. ## Wo das eingesetzt wird Webhook-Trigger sind die eingehende Hälfte von Tales Workflow-API — die Naht, in die dein CRM, dein Order-System oder dein Monitoring-Tool POSTet. Nimm sie für „das ist in unserer Welt passiert, bitte lass dazu einen Tale-Workflow laufen"; greif zur [API-Referenz](/de/develop/api-reference), wenn du stattdessen eine synchrone Antwort willst. Für die ausgehende Hälfte — Tale POSTet auf deine URL, wenn ein Tale-Event passiert — und für den vollen Signier- und Wiederholungs-Vertrag siehe [Webhooks](/de/develop/webhooks). Die Workflow-seitige Konfiguration des Triggers lebt auf der Seite [Workflow-Trigger](/de/platform/automations/triggers). # Einen lokalen LLM-Anbieter anbinden Source: https://tale.dev/docs/de/tutorials/admin/connect-local-provider Ein lokaler Anbieter ist der Weg zu Modellen, die innerhalb deines Perimeters laufen — keine ausgehenden API-Calls, keine Rechnung pro Token, kein Transkript bei Dritten. Dieser Walk bringt eine selbst gehostete Tale-Instanz von „Ich habe einen Ollama-, LM-Studio- oder vLLM-Endpunkt" zu „Ein Agent in der Org ruft ein lokales Modell und die Antwort streamt zurück." Der Walk richtet sich an einen Admin auf einem selbst gehosteten Install; Cloud-Orgs greifen nicht in dein Netzwerk und überspringen diese Seite. Du brauchst die Admin-Rolle in Tale, einen lokalen Inferenz-Server, der vom `tale-platform`-Container erreichbar ist, und ein Modell, das auf diesem Server bereits gezogen oder geladen ist. Die zugrundeliegende Anbieter-Mechanik ist dokumentiert in [Anbieter](/de/self-hosted/configuration/providers); diese Seite walkt den UI-Pfad und verifiziert das Ergebnis End-to-End. ## Bevor du beginnst Bestätige vier Dinge. Deine Rolle ist Admin oder Inhaber — das **Anbieter**-Panel ist darunter versteckt. Dein lokaler Inferenz-Server läuft und beantwortet `GET /v1/models` (oder das Ollama-Äquivalent `GET /api/tags`) von innerhalb des Tale-Docker-Netzwerks. Mindestens ein Modell ist geladen — Ollama-Nutzer haben `ollama pull llama3.1:8b` oder ähnlich gelaufen, LM-Studio-Nutzer haben ein Modell im Server-Tab geladen, vLLM-Nutzer haben den Server mit `--model` auf ein Checkpoint gestartet. Und der Netzwerkpfad von `tale-platform` zum Inferenz-Host ist auf dem Inferenz-Port offen (typisch `11434` für Ollama, `1234` für LM Studio, `8000` für vLLM). ## Schritt 1 — Den Inferenz-Server aus Tale erreichbar machen Der erste Zug ist zu bestätigen, dass `tale-platform` den Inferenz-Server per Hostnamen erreicht. Ohne das bringt jeder Modell-Call einen Connection-Error und der Picker zeigt den Anbieter als **error**. Läuft der Inferenz-Server auf demselben Docker-Host, hängt der erreichbare Hostname davon ab, wo der Server selbst läuft. Ein Ollama-Container im selben Compose-Netzwerk ist `http://ollama:11434`. Ein LM-Studio- oder vLLM-Server, der auf dem Host läuft (außerhalb Compose), ist `http://host.docker.internal:1234` auf macOS und Windows, oder die Bridge-IP des Hosts unter Linux. Lauf einen einmaligen curl aus dem `tale-platform`-Container, um vor dem Öffnen der UI zu verifizieren: ```bash docker compose exec platform curl -sf http://ollama:11434/api/tags ``` Eine JSON-Liste gezogener Modelle ist das Erfolgs-Signal. Ein Connection-refused-Error heißt, der Hostname ist falsch oder der Inferenz-Server lauscht nicht auf dem Interface, das der Container erreicht. ## Schritt 2 — Den Anbieter in Tale registrieren Ein erreichbarer Server tut nichts, bis Tale die URL und die Protokoll-Form kennt, die er spricht. Der Anbieter-Eintrag sagt Tale, wohin Anfragen zu schicken sind und welchen OpenAI-kompatiblen Dialekt zu verwenden. Öffne **Einstellungen > Anbieter** und klick **Anbieter hinzufügen**. Wähl den Anbietertyp, der zu deinem Server passt: **Ollama** für einen Ollama-Server, oder **OpenAI-kompatibel** für LM Studio und vLLM (beide bringen die OpenAI-`/v1`-Form hoch). Füll die **Base-URL** mit dem Wert, den du in Schritt 1 verifiziert hast; lass das API-Key-Feld für Ollama leer, setz es auf einen beliebigen String für LM Studio (der Server ignoriert ihn), setz es auf deinen konfigurierten Token für vLLM, wenn du den Server mit `--api-key` gestartet hast. Klick **Speichern**. Tale ruft sofort den Modell-Listen-Endpunkt des Anbieters; die Zeile wird grün und der Modell-Picker füllt sich mit dem, was der Server meldet. ## Schritt 3 — Die Modelle allowlisten, die aufrufbar sein sollen Ein registrierter Anbieter ohne allowlistete Modelle ist für jeden Agent unsichtbar. Die Allowlist ist der Vertrag zwischen Org und Anbieter — das Modell zu wählen ist das Tor. In der Anbieter-Zeile öffnest du den Modell-Picker. Jedes Modell aus der Upstream-Liste zeigt eine Checkbox plus das Tag, das Tale abgeleitet hat (`chat`, `embedding`, `vision`). Hak die Modelle ab, die Agenten aufrufen sollen; ein chat-getaggtes Modell ist das, woran ein Agent standardmäßig gebunden ist. Klick **Allowlist speichern**. Soll das lokale Modell der org-weite Default für neue Chats sein, scroll oben in die Anbieter-Liste und wähl es unter **Standardmodell**. Bestehende Agenten behalten ihre vorherige Bindung; neue landen mit der nächsten Anfrage auf dem lokalen Modell. ## Schritt 4 — Mit einem Agent-Chat verifizieren Der Beweis, dass die Verdrahtung funktioniert, ist eine Chat-Antwort, die vom lokalen Server streamt. Ohne diesen Schritt weißt du nicht, ob der Modell-Picker bloß richtig _aussieht_. Öffne oder erstelle einen Agent, setz sein Modell auf eines der lokalen Modelle, die du allowlistet hast, und starte einen Chat mit einem kurzen Prompt (`Antworte mit dem einzelnen Wort "bereit"`). Die Antwort streamt innerhalb weniger Sekunden in Tokens herein; die Tool-Call-Karte des Chats zeigt den Modellnamen und den Anbieter, den du registriert hast. Tail das Inferenz-Server-Log auf dem Host, während du den Prompt schickst — Ollama loggt die Anfrage-Zeile, LM Studio druckt eine Anfrage-Zusammenfassung, vLLM druckt die Generation-Latenz. Die Anfrage am lokalen Server zu sehen ist die Verifikation, dass der Traffic in deinem Netzwerk bleibt und nicht durch eine externe API springt. ## Troubleshooting - **Symptom:** Anbieter-Zeile zeigt **error** mit `connection refused`. **Ursache:** Die Base-URL ist vom `tale-platform`-Container nicht erreichbar. **Fix:** Wiederhole den `docker compose exec platform curl` aus Schritt 1; pass den Hostnamen an (oft `host.docker.internal` auf macOS/Windows, die Bridge-IP unter Linux). - **Symptom:** Der Modell-Picker ist nach **Speichern** leer. **Ursache:** Der Inferenz-Server ist erreichbar, aber es sind keine Modelle geladen. **Fix:** Lauf `ollama pull <model>` oder lad ein Modell in LM Studio / vLLM, dann klick **Modelle aktualisieren** auf der Anbieter-Zeile. - **Symptom:** Die Chat-Antwort ist ein Fehler-Toast (`model not found`). **Ursache:** Der Modellname, an den der Agent gebunden ist, stimmt nicht mit der Upstream-ID überein. **Fix:** Öffne das Modell-Dropdown des Agenten und wähl aus der Live-Liste neu — Ollama-Tags wie `:latest` zählen Upstream und müssen exakt passen. - **Symptom:** Das Speichern des Anbieters wird abgelehnt, weil die Base-URL auf `localhost`, `127.0.0.1` oder eine private IP zeigt. **Ursache:** Tale blockiert private und Loopback-Anbieter-Hosts standardmässig als SSRF-Schutz. **Fix:** Nutz stattdessen den netzinternen Hostnamen (`http://ollama:11434`, `http://host.docker.internal:1234`); wenn du auf eine private oder Loopback-Adresse zeigen musst, setz `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS=1` am platform-Service. ## Wo das hingehört Ein lokaler Anbieter ist die Naht zwischen Tale und deinen eigenen GPUs — dieselbe Allowlist-Mechanik wie bei einem Cloud-Anbieter, aber kein Traffic verlässt den Host. Die natürlichen nächsten Lesungen sind [Anbieter](/de/self-hosted/configuration/providers) für das Datei-Form-Äquivalent dessen, was du eben in der UI gemacht hast, und [Hardening](/de/self-hosted/operate/security/hardening) für die Egress-Allowlist-Garantien, die einen Agent davon abhalten, versehentlich auf ein Cloud-Modell zurückzufallen, wenn das lokale nicht erreichbar ist. # Das Outlook-Add-in installieren Source: https://tale.dev/docs/de/tutorials/admin/office-add-in Das Outlook-Add-in blendet eine Tale-Sidebar in Outlook im Web, auf dem Desktop und mobil ein. Aus der Sidebar wählt ein Mitglied einen Agent, lässt den offenen Mail-Thread als Kontext einfliessen und bekommt einen Antwort-Draft zurück, ohne die App zu wechseln. Dieser Spaziergang richtet sich an einen Admin, der das Add-in organisationsweit ausrollt; er deckt den Manifest-Deploy, das Anmelden und die Verifikation ab. Du brauchst die Admin-Rolle in Tale, einen Microsoft-365-Tenant, in dem du Integrated Apps verwaltest, und eine Tale-Instanz, die aus der Microsoft-365-Cloud erreichbar ist. Cloud-Orgs sind standardmässig erreichbar; selbst gehostete Instanzen brauchen eine öffentliche HTTPS-URL. ## Bevor du beginnst Bestätige drei Dinge auf der Microsoft-Seite: du bist Global Administrator (oder hast die Exchange-Admin-Rolle mit Integrated Apps), die zentrale Bereitstellung ist für deinen Tenant aktiviert, und das Test-Postfach hat Add-ins nicht über eine Mailbox-Policy gesperrt. Auf der Tale-Seite öffne **Einstellungen > Integrationen** und prüfe, dass **Microsoft 365** gelistet ist — dort veröffentlicht das Add-in die Manifest-URL. ## Schritt 1 — Die Manifest-URL aus Tale holen Das Add-in spricht mit Tale über ein Manifest-XML, das das Microsoft-365-Admin-Center hostet. Tale generiert das Manifest pro Instanz, damit die Sidebar auf deine URL zeigt und nicht auf einen geteilten Multi-Tenant-Endpunkt. Öffne **Einstellungen > Integrationen > Microsoft 365** und kopier die **Add-in-Manifest-URL**, die das Panel zeigt. Du solltest eine URL sehen, die auf `/integrations/office/manifest.xml` endet. Öffne sie in einem neuen Tab, um zu bestätigen, dass sie XML zurückgibt und keine HTML-Fehlerseite — bricht das ab, ist deine Instanz von aussen nicht erreichbar oder die Integration ist deaktiviert. ## Schritt 2 — Übers Microsoft-365-Admin-Center ausrollen Das Manifest sagt Microsoft 365, welche Postfächer die Sidebar sehen dürfen und von welcher URL sie geladen wird. Zentrale Bereitstellung ist der unterstützte Pfad; das Side-Loading pro Nutzer funktioniert, übersteht aber keine Postfach-Migration. Öffne das Microsoft-365-Admin-Center, navigiere zu **Einstellungen > Integrierte Apps > Eigene Apps hochladen**, wähl **Office-Add-in** und **Link zur Manifest-Datei bereitstellen** und füg die URL aus Schritt 1 ein. Wähl die Rollout-Zielgruppe — den ganzen Tenant, eine Sicherheitsgruppe oder eine konkrete Nutzerliste. Senden. Microsoft bestätigt den Deploy mit einem grünen Banner; der Rollout erreicht Postfächer typischerweise innerhalb einer Stunde, bei grossen Tenants auch ein paar Stunden später. ## Schritt 3 — Aus der Sidebar anmelden Öffne Outlook als Nutzer in der Rollout-Zielgruppe, klick eine beliebige Mail an und such das Tale-Icon im Nachrichten-Ribbon. Ein Klick öffnet die Sidebar; beim ersten Öffnen verlangt sie eine Anmeldung mit dem Tale-Konto. Die Anmeldung läuft per OAuth über die Tale-Instanz — derselbe Identity-Anbieter wie in der Web-App. Nach der Anmeldung listet die Sidebar die für den Nutzer verfügbaren Agenten. Einen auswählen und **Antwort entwerfen** klicken zieht den offenen Mail-Thread als Kontext heran und streamt eine Antwort in die Sidebar. Der Nutzer prüft, bearbeitet und klickt **Einfügen**, um sie ins Outlook-Kompositionsfenster zu droppen. ## Wo das eingesetzt wird Das Add-in ist der leichteste Weg zu „Tale dort, wo deine Mitglieder ohnehin arbeiten" — kein Portal-Wechsel, kein Copy-Paste. Die Sidebar ist eine dünne Hülle um dieselben Agenten, die du in [Agent erstellen](/de/platform/agents/create) veröffentlichst; Änderungen an Instruktionen, Wissen oder Tools eines Agenten landen mit der nächsten Anfrage in der Sidebar. Für die breitere Integration-Story — Slack, Gmail, eigene MCP-Server — siehe [Integrationen-Überblick](/de/platform/integrations/overview). Betreibst du eine selbst gehostete Instanz und ist die Manifest-URL aus Microsoft 365 nicht erreichbar, deckt die Seite [Linux-Server](/de/self-hosted/install/linux-server) die Voraussetzung „öffentliches HTTPS" ab. # Meeting-Transkripte in die Wissensdatenbank pipen Source: https://tale.dev/docs/de/tutorials/admin/meeting-transcription Ein Meeting-Transkript ist eines der wertvollsten Dokumente, die ein Projekt führen kann — Namen, Entscheidungen, Follow-ups, alles an einem durchsuchbaren Ort. Dieser Walk integriert Meetily, ein lokales Meeting-Transkriptions-Tool, mit einem Tale-Projekt, damit jedes Transkript, das Meetily erzeugt, in der Wissensdatenbank des Projekts als Dokument von selbst landet. Der Walk richtet sich an einen Admin auf einer selbst gehosteten Tale-Instanz, der sie mit einem Meetily-Install im selben Netzwerk paart. Du brauchst die Admin-Rolle in Tale, einen Meetily-Install, der vom `tale-platform`-Container erreichbar ist, und ein Projekt in Tale mit einer Wissensdatenbank, in die die Transkripte geroutet werden. Das Wissensdatenbank-Konzept lebt unter [Wissensdatenbank](/de/platform/knowledge/overview); diese Seite ist der Integrations-Walk, nicht die Konzept-Seite. ## Bevor du beginnst Bestätige vier Dinge. Deine Rolle ist Admin oder Inhaber in Tale — das **Integrationen**-Panel ist darunter versteckt. Meetily läuft und produziert Transkripte in einem Format, das Tale akzeptiert (Markdown, Klartext oder VTT). Der Meetily-Host ist von `tale-platform` über seinen Webhook- oder Shared-Folder-Pfad erreichbar. Und das Zielprojekt existiert in Tale bereits mit einer angehängten Wissensdatenbank — die Integration schreibt _in_ eine Wissensdatenbank, sie erstellt keine. ## Schritt 1 — Den Auslieferungspfad wählen Meetily kann Transkripte in zwei Formen an Tale übergeben, und sie haben unterschiedliche operative Eigenschaften. Die Wahl legt fest, wie der Rest des Walks zu lesen ist. Der **Webhook**-Pfad lässt Meetily jedes fertige Transkript an einen Tale-Ingest-Endpunkt POSTen, sobald das Meeting endet; das Transkript ist Sekunden nach Schließen des Meetings in der Wissensdatenbank. Der **Shared-Folder**-Pfad lässt Meetily Transkripte als Dateien in ein Verzeichnis schreiben, das die Tale-Plattform jede Minute pollt; die Latenz beträgt bis zu eine Minute, aber der Pfad braucht keine öffentliche URL und übersteht Meetily-Neustarts ohne Retry-Logik. Wähl Webhook, wenn beide Dienste im selben Netzwerk laufen und du schnelles Indizieren willst; wähl Shared Folder, wenn Meetily auf einer Workstation läuft, die unregelmäßig aufwacht, oder wenn das Operations-Team einen dateibasierten Audit-Trail bevorzugt. ## Schritt 2 — Den Ingest-Endpunkt oder Ordner in Tale erstellen Tale muss wissen, wo Transkripte landen werden und zu welchem Projekt sie gehören. Ohne diese Bindung kommen Transkripte an, aber keine Wissensdatenbank beansprucht sie. Öffne **Einstellungen > Integrationen**, klick **Integration hinzufügen** und wähl **Meeting-Transkripte**. Wähl das Projekt aus dem Dropdown — die Wissensdatenbank, die das Projekt nutzt, ist das Ziel. Wähl den Auslieferungspfad, den du in Schritt 1 gewählt hast. Hast du Webhook gewählt, generiert Tale eine URL der Form `https://<dein-host>/integrations/transcripts/<token>` und zeigt sie einmal. Kopier die URL; sie funktioniert auch als Bearer-Credential, also behandle sie wie ein Geheimnis. Hast du Shared Folder gewählt, fragt Tale nach dem Pfad auf der Disk, den `tale-platform` beobachten soll (typisch `/data/transcripts/<project-slug>`). Erstell das Verzeichnis auf dem Host, gib ihm Gruppen-Eigentum, das dem `tale-platform`-Container-User entspricht, und bestätig. ## Schritt 3 — Meetily auf Tale zeigen lassen Meetily muss jetzt wissen, wohin jedes Transkript zu liefern ist. Die Einstellungen leben in der eigenen Config von Meetily. Für den Webhook-Pfad öffnest du die Einstellungen von Meetily und fügst ein Webhook-Ziel mit der URL aus Schritt 2 hinzu. Wähl das Transkript-Format — Markdown ist das, was sich in einer Tale-Dokument-Vorschau am besten liest, aber VTT und Klartext werden beide korrekt indiziert. Für den Shared-Folder-Pfad setz das Transkript-Ausgabe-Verzeichnis von Meetily auf den Pfad, den du in Schritt 2 erstellt hast. Stell sicher, dass Meetily eine Datei pro Meeting schreibt, benannt nach Meeting-Titel und Zeitstempel. Beende ein kurzes Test-Meeting in Meetily und beobachte das Tale-Integrationen-Panel. Die Integrations-Zeile zeigt einen **Letzte Auslieferung**-Zeitstempel, der innerhalb einer Minute (Folder-Modus) oder weniger Sekunden (Webhook-Modus) aktualisiert. ## Schritt 4 — Verifizieren, dass das Dokument landet und indiziert Der Beweis, dass die Verdrahtung funktioniert, ist ein Transkript, das in der Wissensdatenbank als durchsuchbares Dokument sichtbar ist. Ohne diesen Schritt weißt du nicht, ob Tale die Datei empfangen _und_ indiziert hat. Öffne das Zielprojekt, navigiere zu seiner Wissensdatenbank und such das neue Transkript oben in der Dokumentenliste. Klick in die Vorschau — das Transkript rendert als Dokument mit dem Meeting-Titel als Dokumentnamen und dem Meeting-Datum als Created-at. Wart, bis das Indizier-Badge sich klärt (wenige Sekunden für ein kurzes Transkript, bis zu eine Minute für ein langes), dann lauf eine Suche nach einem Namen oder einer Phrase, die du aus dem Test-Meeting erinnerst. Das Transkript sollte das erste Ergebnis mit der hervorgehobenen Phrase sein. Liegt das Dokument vor, bleibt das Indizier-Badge aber orange, ist die Indexierung im Rückstand — die Seite [Troubleshooting](/de/self-hosted/operate/observability/troubleshooting) nennt die Symptome. ## Vertrauensgrenze Die Integration überquert in jede Richtung ein Netzwerk und die Datenform zählt. - **Meetily → Tale.** Der Transkript-Body geht rüber, plus Meeting-Titel, Zeitstempel und alle Sprecher-Labels, die Meetily angehängt hat. Audio geht nicht rüber — Meetily transkribiert lokal und nur der Text wird ausgeliefert. Der Webhook-Pfad nutzt HTTPS mit dem Bearer-Token in der URL; der Folder-Pfad nutzt einen Dateisystem-Pfad ohne Netzwerk überhaupt. - **Tale → Meetily.** Nichts. Die Integration ist einseitig; Tale ruft nie zurück in Meetily. - **Tale → externe Dienste.** Der Transkript-Text geht zu dem Embedding-Anbieter, der an die Wissensdatenbank gebunden ist. Ist der Embedding-Anbieter ein lokaler (Ollama, LM Studio, vLLM über [Einen lokalen LLM-Anbieter anbinden](/de/tutorials/admin/connect-local-provider)), verlässt kein Transkript-Text den Host. Ist der Embedding-Anbieter OpenAI, Anthropic oder ein anderer gehosteter Endpunkt, wird der Transkript-Text gemäß der Daten-Handhabungs-Policy dieses Anbieters zur Vektorisierung dorthin geschickt. Enthalten Transkripte Inhalte, die die Org nicht an einen Cloud-Anbieter senden kann, ist das unterstützte Pattern, die Wissensdatenbank des Projekts an ein lokales Embedding-Modell zu binden. Die Anbieter-Bindung passiert in den Wissensdatenbank-Einstellungen, nicht in dieser Integration. ## Wo das hingehört Die Meeting-Transkriptions-Integration ist das sauberste Beispiel für „Tale indiziert, was deine anderen Tools schon produzieren" — kein Copy-Paste, kein manueller Upload, kein zusätzlicher Schritt im Meeting-Workflow. Die natürlichen nächsten Lesungen sind [Wissensdatenbank](/de/platform/knowledge/overview) dafür, wofür das indizierte Transkript dann in einem Agent verwendet werden kann, und [Einen lokalen LLM-Anbieter anbinden](/de/tutorials/admin/connect-local-provider), wenn der Abschnitt oben dich dazu drängt, den Embedding-Schritt auf dem Host zu behalten. # Einen Agent mit Wissen bauen Source: https://tale.dev/docs/de/tutorials/editor/agent-with-knowledge Ein Agent mit Wissen ist die Form, zu der du greifst, wenn das Modell aus bestimmten Dokumenten antworten soll — deinem Produkt-Handbuch, deinen Richtlinien, den Call-Notizen des letzten Quartals — und nicht aus dem, was es im Training gelernt hat. Der Agent holt zur Antwortzeit Chunks aus den gebundenen Quellen und zitiert sie. Dieser Spaziergang führt einen frischen Agent von „ich will, dass er meine Docs kennt" zu „die Antwort zitiert das richtige Dokument" auf einer Instanz. Du brauchst eine Editor-Rolle, die Fähigkeit, Dokumente in die Wissensdatenbank hochzuladen, und etwa drei zu bindende Dokumente. Die konzeptuelle Seite lebt in [Agent-Wissen](/de/platform/agents/knowledge); dieser Spaziergang ist der End-to-End-Mechanismus. ## Bevor du beginnst Bestätige drei Dinge. Deine Rolle ist mindestens Editor — die Agent-Bearbeitung ist auf Editor und höher begrenzt. Du hast mindestens drei Dokumente zum Hochladen bereit (PDFs, DOCX, Markdown — alles, was die Wissensdatenbank akzeptiert). Du hast einen Anbieter konfiguriert, damit der Agent laufen kann — ohne diesen scheitert die Test-Antwort am Ende beim Modell-Call. ## Schritt 1 — Dokumente in die Wissensdatenbank hochladen Der erste Zug ist, die Dokumente in Tales Wissensdatenbank zu legen. Dokumente ausserhalb der Wissensdatenbank lassen sich nicht binden; der Agent sieht nur Quellen, die er benennen kann. Öffne **Wissen > Dokumente** und klick **Hochladen**. Zieh die drei Dokumente hinein, gib ihnen sinnvolle Titel und warte, bis die Status-Spalte für jedes **Bereit** zeigt. Der Status durchläuft `hochgeladen → wird verarbeitet → bereit`; die Verarbeitung chunkt das Dokument und berechnet Embeddings. Ein typisches PDF erreicht **Bereit** in ein, zwei Minuten. Bleibt ein Dokument länger als fünf Minuten auf `wird verarbeitet`, öffne seine Zeile, um den Fehler zu sehen — die häufigste Ursache ist ein nicht unterstütztes Format (reine Bild-PDFs, passwortgeschützte Dateien) oder eine Datei grösser als das Upload-Limit der Org. ## Schritt 2 — Den Agent erstellen Ein gebundenes Dokument hängt an einem Agent, also muss der Agent zuerst existieren. Öffne **Agenten > Neuer Agent** und füll die vier Knöpfe als Basis aus: - **Name** — `Docs Q&A` - **Instruktionen** — `You answer questions strictly from the bound documents. If you cannot find the answer in the documents, say so explicitly. Cite the document title for every claim.` - **Tools** — **RAG** einschalten; alles andere aus - **Modell** — was immer die Org als Default nutzt Speichern und veröffentlichen. Der Agent existiert nun, hat aber kein Wissen — er wird jede Frage verweigern, weil er keine Quelle findet. ## Schritt 3 — Die Dokumente binden Die Bindung ist die Naht, die dem Agent Retrieval-Zugriff auf eine Teilmenge der Wissensdatenbank gibt. Öffne den Tab **Wissen** des Agenten und klick **Agent-Wissen**. Wähl die drei Dokumente aus Schritt 1 und speicher. Der Wissen-Tab listet jetzt drei gebundene Quellen. Das RAG-Tool des Agenten holt nur aus diesen drei; nichts anderes in der Wissensdatenbank ist von diesem Agent aus erreichbar, auch keine anderen Dokumente in derselben Bibliothek. ## Schritt 4 — Eine Frage stellen und das Zitat prüfen Öffne einen Chat mit `Docs Q&A` und stell eine Frage, die eines der Dokumente beantwortet. Die Antwort streamt mit inline gesetzten Zitaten herein — Hovern zeigt den Dokument-Titel, Klicken öffnet das Dokument am zitierten Chunk. Stell eine Frage, die keines der Dokumente abdeckt; der Agent sollte gemäss Instruktion explizit verweigern und keine Antwort erfinden. Erfindet der Agent trotzdem eine Antwort, sind die Instruktionen nicht streng genug — füg einen expliziten Verweigerungs-Fall hinzu („If you cannot find the answer in the bound documents, respond with exactly: 'I could not find this in the bound documents.'") und veröffentliche erneut. ## Wo das eingesetzt wird Die vier Züge oben sind der kanonische „Agent, der aus deinen Docs antwortet"-Bau: hochladen, Agent mit aktivem RAG erstellen, binden, mit einem Zitat verifizieren. Dieselbe Form skaliert — bind zehn Dokumente statt drei, füg eine Website oder einen Kunden-Datensatz hinzu, wechsle das Modell. Die Bindungen, nicht das Modell, machen den Agent zu deinem. Für die konzeptuelle Seite, wie Retrieval mit den anderen Knöpfen des Agenten zusammenspielt, siehe [Agent-Konzepte](/de/platform/agents/concepts). Für die breitere Wissensdatenbank-Geschichte — Kunden, Produkte, Anbieter, Websites — siehe [Wissens-Überblick](/de/platform/knowledge/overview). # Einen Workflow mit Freigabe bauen Source: https://tale.dev/docs/de/tutorials/editor/workflow-with-approvals Ein Workflow mit einer menschlichen Entscheidung in der Mitte ist die Form, zu der du greifst, wenn die Arbeit aus Entwurf, Review und Aktion besteht — und du eine Person zwischen Entwurf und Aktion willst. Der Lauf pausiert als **Wartet auf Eingabe**, bis jemand antwortet; der nächste Schritt feuert nur bei grünem Licht. Dieser Spaziergang baut so einen Daily-Summary-Workflow, und unterwegs begegnest du beiden menschlichen Toren: dem Genehmigen des KI-Editor-Vorschlags und dem Beantworten des pausierten Laufs. Du brauchst eine Editor-Rolle und einen Agent, der einen Entwurf produziert (der erste nützliche Agent aus [Deinen ersten Agent bauen](/de/tutorials/editor/first-agent-end-to-end) reicht). Die konzeptuelle Seite lebt in [Automatisierungskonzepte](/de/platform/automations/concepts) und [Genehmigungs-Konzepte](/de/platform/approvals/concepts); dieser Spaziergang ist der End-to-End-Mechanismus. ## Bevor du anfängst Prüf drei Dinge. Deine Rolle ist mindestens Editor — Workflow-Bearbeitung ist ab Editor aufwärts freigeschaltet. Du hast einen Entwurfs-Agent bereit; ohne ihn hat der Entwurfs-Schritt nichts aufzurufen. Und du kannst das Review selbst beantworten — der pausierte Lauf wartet auf einen Menschen, und in diesem Spaziergang bist du das. ## Schritt 1 — Einen Workflow im Editor öffnen Workflows leben in der Automatisierung, die sie antreiben: Öffne die Automatisierung, und ihr Tab **Editor** ist der Workflow, mit dem Schritt-Graphen auf der Leinwand. Öffne für diesen Spaziergang einen Workflow, der dir gehört, oder einen aus dem Task-Ops-Paket deiner Org — alles funktioniert, was du bearbeiten darfst, denn die neue Definition baut ohnehin der KI-Editor für dich. ## Schritt 2 — Dem KI-Editor den Workflow beschreiben Schalte den **KI-Editor** in der Leinwand-Werkzeugleiste ein und beschreib die ganze Form in einer Nachricht: > Lass jeden Werktag um 08:00 den Agent <dein Agent> die ungelesenen Kundennachrichten von gestern in einen Absatz zusammenfassen, dann einen Menschen den Entwurf prüfen, und schick nur den freigegebenen Text an den Team-Kanal. Der KI-Editor antwortet mit einer Vorschlagskarte — **Workflow erstellen** mit der Schrittzahl, oder **Workflow aktualisieren**, wenn er den geöffneten umbaut. Solange die Karte aussteht, passiert an der Definition nichts: Klapp sie auf, prüf die gelisteten Schritte — ein **LLM**-Schritt für den Entwurf, die Review-Pause, der Versand — und genehmige sie. Die Änderung wird angewendet und versioniert wie jedes manuelle Speichern. ## Schritt 3 — Den Zeitplan anhängen Wechsle zum Tab **Trigger** und klick **Zeitplan hinzufügen**. Nimm die Vorlage **Täglich** und pass den Cron auf Werktage an (`0 8 * * 1-5`) — oder beschreib die Zeit in Alltagssprache und klick **Generieren**, damit die KI den Cron schreibt. **Workflow-Variablen** füllt sich aus dem Eingabeschema des Workflows vor; lass es wie vorgeschlagen. Die Zeile erscheint mit bereits eingeschaltetem **Aktiv**-Schalter. ## Schritt 4 — Laufen lassen und das Review beantworten Zurück im Editor: Öffne **Workflow testen**, füg das vorgeschlagene Eingabe-JSON ein und klick **Ausführen**. Das Panel spiegelt den Lauf Schritt für Schritt: Der Entwurfs-Schritt feuert, dann pausiert der Lauf — **Wartet auf Eingabe** — und das Review kommt als Formular-Karte mit dem Entwurf an. Füll sie aus und klick **Antwort absenden**, um freizugeben, oder **Anders antworten**, um im Freitext zurückzugeben; der Lauf setzt mit deiner Antwort fort und der Versand-Schritt feuert. Öffne den Tab **Ausführungen** und klapp den Lauf auf: Das Journal zeigt einen Eintrag pro Schritt — den Entwurf des Agents, wer das Review beantwortet hat und wie, und den Versand mit seiner Ausgabe. Dieses Journal ist der Audit-Trail; derselbe Datensatz entsteht für jeden künftigen geplanten Lauf. ## Wo das hinführt Entwerfen, entscheiden, handeln — mit der Entscheidung bei einem Menschen — ist der kleinste nützliche Workflow mit Freigabe, und du hast ihn gebaut, ohne einen einzigen Schritt von Hand zu setzen: Der KI-Editor hat vorgeschlagen, du hast genehmigt, der Lauf hat gefragt, du hast geantwortet. Dieselbe Form skaliert — häng ein zweites Review vor einen destruktiven Schritt, oder lass dir von [Genehmigungen in Workflows](/de/platform/automations/approvals-in-workflows) die übrigen Tore rund um einen Workflow zeigen. Für das Vokabular hinter Definition, Trigger und Ausführung ist [Automatisierungskonzepte](/de/platform/automations/concepts) die Seite, die dieser Spaziergang vorausgesetzt hat. # Arbeit an einen Worker geben Source: https://tale.dev/docs/de/tutorials/editor/delegate-between-agents Wenn eine Anfrage ihren eigenen fokussierten Kontext verdient — zitierte Recherche, Massen-Extraktion, ein langer Entwurf — startet der Assistent einen **Worker**: einen flüchtigen Agenten, zusammengestellt für genau diese Aufgabe, mit genau den Fähigkeiten, die der Assistent ihm aus seinem eigenen Satz mitgibt. Es gibt nichts zu konfigurieren; dieser Durchlauf fährt einen Recherche-Job von Anfang bis Ende und zeigt dir, wie du die Job-Karte liest. Die konzeptionelle Seite (Fähigkeits-Teilmengen, Budgets, Methodiken) steht in [Agent-Worker](/platform/agents/delegation). ## Bevor du beginnst Du brauchst einen chatfähigen Agenten (der eingebaute Assistent funktioniert direkt) auf einem Modell mit Tool-Calling. Für Live-Webquellen verbinde eine Such-Integration wie Tavily unter **Einstellungen > Integrationen** — ohne sie fällt der Worker auf einfaches Web-Abrufen zurück und sagt das in seinem Ergebnis. ## Schritt 1 — Frag nach etwas, das einen Worker verdient Öffne einen Chat mit `Assistent` und bitte um offene, zitierbare Arbeit, zum Beispiel: `Recherchiere den Stand von Feststoffbatterien — Markt, wichtigste Akteure, zitierte Quellen.` Eine schnelle Faktenfrage startet keinen Worker (und sollte es auch nicht); Worker sind für Aufgaben, die von Isolation profitieren. ## Schritt 2 — Beobachte die Job-Karte Der Assistent ruft `spawn_agent` auf, und unter seinem Zug erscheint eine **Job-Karte**: der Name des Workers, ein Live-Status und die eigene Fortschritts-Checkliste des Workers, die sich füllt, während er plant und die Teilfragen abarbeitet. Die Karte blockiert nie den Eingabebereich — du kannst weitertippen, während der Worker läuft. Zeigt die Karte einen „Übersprungen“-Hinweis, hat der Assistent etwas außerhalb seiner eigenen Freigaben angefragt (etwa eine nicht verbundene Integration); der Lauf geht mit dem Rest weiter, und der Hinweis sagt dir, was du fürs nächste Mal verbinden solltest. ## Schritt 3 — Lies Ergebnis und Protokoll Ist der Job fertig, faltet der Assistent das Ergebnis des Workers in seine Antwort — bei Recherche ein Fazit, Kernpunkte mit Inline-Zitaten und Quellen. Klappe auf der Karte **Worker-Aktivität** auf, um das vollständige Protokoll zu sehen: jede Suche, jeden Tool-Aufruf und die Überlegungen des Workers. Dieses Protokoll ist der Audit-Trail, auf den du zeigst, wenn jemand fragt, was der Agent tatsächlich getan hat. ## Schritt 4 — Wenn etwas schiefgeht Ein Worker, dem die Zeit ausgeht oder der auf einen Fehler stößt, endet mit sichtbarem Status auf der Karte — `Zeit abgelaufen` oder `Fehlgeschlagen` — mit intaktem Teilfortschritt. Der Assistent berichtet, was er bekommen hat, und macht selbst weiter, wo er kann. Nichts scheitert still: Brauchte der Worker eine Eingabe, die nur du geben kannst, fragt dich der Assistent direkt. ## Wo das hingehört Eine Anfrage, ein Worker, eine Karte ist die kleinste nützliche Form. Dieselbe Mechanik skaliert auf mehrere Worker in einem Zug — jeder bekommt seine eigene Karte, seinen eigenen Fortschritt und sein eigenes Protokoll. Für feste Stufen mit Freigaben oder Zeitplänen dazwischen greif stattdessen zu einem [Workflow](/de/platform/automations/concepts). # Deinen ersten Agent bauen Source: https://tale.dev/docs/de/tutorials/editor/first-agent-end-to-end Ein erster Agent ist das kleinste nützliche Ding in Tale: Instruktionen plus Modell, manchmal mit einem Tool oder einem gebundenen Dokument. Dieser Spaziergang dreht die vier Knöpfe der Reihe nach — Instruktionen, Wissen, Tools, Modell — und hinterlässt dir einen veröffentlichten Agent, der im Chat eine echte Frage beantwortet. Die Form verallgemeinert sich: jeder spätere Agent ist dieselben vier Züge mit anderen Entscheidungen. Du brauchst eine Editor-Rolle und ein konfiguriertes Chat-getaggtes Modell beim Anbieter der Org. Die konzeptuelle Seite lebt in [Agent-Konzepte](/de/platform/agents/concepts); dieser Spaziergang ist der End-to-End-Mechanismus. ## Bevor du beginnst Bestätige drei Dinge. Deine Rolle ist mindestens Editor — die Agent-Bearbeitung ist auf Editor und höher begrenzt. Die Org hat einen Anbieter konfiguriert und mindestens ein Chat-getaggtes Modell darauf; ohne das scheitert die Test-Antwort am Ende beim Modell-Call. Du hast eine Frage im Kopf, die der Agent beantworten soll — wähl etwas eng genug, dass ein Absatz Instruktionen sie rahmen kann, etwa „fass eine eingehende Kundennachricht in einen Satz plus eine empfohlene nächste Aktion zusammen". ## Schritt 1 — Die Instruktionen schreiben Instruktionen sind der System-Prompt — die Prosa, die jede Antwort rahmt. Der erste Knopf ist der, bei dem die meisten überdrehen. Öffne **Agenten > Neuer Agent** und setze: - **Name** — `Triage assistant` - **Instruktionen** — `You read a customer message and produce two lines. Line one: a one-sentence summary in plain English. Line two: a recommended next action — reply, escalate, or close. If the message is blank or off-topic, refuse and say so.` Speicher vorerst als Entwurf; veröffentlichen kommt nach den anderen Knöpfen. Kurze, meinungsstarke, konkrete Instruktionen schlagen lange — halt die Regeln unter einem Absatz. ## Schritt 2 — Über das Wissen entscheiden Wissen ist das, worauf der Agent zur Antwortzeit zurückgreifen kann. Lass Wissen für diesen ersten Agent leer: die Aufgabe ist, die Nachricht zu lesen, nicht etwas zu holen. Der Wissen-Tab bleibt unangetastet. Wolltest du später Wissen ergänzen — etwa eine Eskalations-Matrix, die der Agent konsultieren soll — würdest du das Dokument hochladen, den **Wissen**-Tab des Agenten öffnen und es binden. Der ganze Mechanismus liegt in [Agent mit Wissen](/de/tutorials/editor/agent-with-knowledge). ## Schritt 3 — Die Tools wählen Tools sind das, was der Agent jenseits von Text-Antworten tun kann. Für Triage brauchst du keine Tools: der Agent liest Input und schreibt Output. Öffne den Tab **Tools** und lass jeden Schalter aus. Jedes Tool, das du gewährst, erweitert die Vertrauensgrenze; halt die Liste kurz. Soll der Agent die empfohlene Aktion in ein CRM zurückschreiben, würdest du später den entsprechenden Integrations-Tool-Schalter aktivieren — aber nicht, bevor die reine Text-Variante funktioniert. ## Schritt 4 — Modell wählen und veröffentlichen Öffne den Tab **Modell** und wähl als primäres den Org-Default; setz ein kleineres Modell als Fallback, damit der Agent läuft, wenn das primäre rate-limited ist. Speicher, dann klick **Veröffentlichen**. Der Agent ist nun für alle mit passender Rolle im Chat sichtbar. Öffne einen Chat mit `Triage assistant` und füg eine echte Kundennachricht ein. Die Antwort sollte gemäss Instruktionen in zwei Zeilen landen — Ein-Satz-Zusammenfassung und empfohlene Aktion. Driftet das Format ab, zieh die Instruktionen straffer und veröffentliche neu; das ist die Schleife, in der du am meisten Zeit verbringst. ## Wo das eingesetzt wird Vier Knöpfe, ein veröffentlichter Agent, eine verifizierte Antwort: dieselbe Form, der jeder später gebaute Agent folgt. Die nächsten Spaziergänge spezialisieren sich auf je einen Knopf — [Agent mit Wissen](/de/tutorials/editor/agent-with-knowledge) auf den zweiten, [Arbeit an einen Worker geben](/de/tutorials/editor/delegate-between-agents) auf den dritten. Für die Konzept-Seite, die die vier Knöpfe und ihre Trade-offs benennt, siehe [Agent-Konzepte](/de/platform/agents/concepts). Für Versionierung und Rollback, sobald der Agent reift, siehe [Agent-Versionen](/de/platform/agents/versions). # Trust und Compliance Source: https://tale.dev/docs/de/cloud/trust-and-compliance Trust und Compliance auf Cloud ist die Seite, die ein Auditor will. Sie benennt die Frameworks, gegen die die Plattform zertifiziert ist, trennt Verantwortlichkeiten zwischen Tale und deiner Org sauber, listet die für dich verfügbaren Datenschutzkontrollen und sagt dir, wen du anrufst, wenn etwas schiefgeht. Der Inhalt hier ist beschreibend — was heute ausgeliefert wird, welche Belege Tale auf Anfrage übergeben kann. Die rechtlichen Dokumente selbst (DPA, Terms, Privacy) leben unter [Legal](/de/legal/privacy); diese Seite ist die schnelle Betreiber-Referenz. ## Eine durchgespielte Kontrolle — Audit-Logs von Anfang bis Ende Der Compliance-Verantwortliche der Org muss nachweisen, dass „jede Änderung an Zugriffskontrollen mit Akteur, Ziel und Zeitstempel protokolliert wird". Tales [Audit-Logs](/de/platform/admin/governance/audit-logs) zeichnen jede Mitgliedseinladung, Rollenänderung, Entfernung und 2FA-Zurücksetzung mit der User-ID des Akteurs, der ID des betroffenen Mitglieds und einem ISO-Zeitstempel auf. Logs sind unveränderlich — einen Schnappschuss wiederherzustellen verändert sie nicht — und gemäss dem konfigurierten Floor der Org aufbewahrt. Der Verantwortliche exportiert einen Datumsbereich als CSV, übergibt ihn dem Auditor, und das durchgespielte Beispiel räumt die Kontrolle ab. ## Zertifizierungen und Frameworks Tale Cloud ist derzeit gegen die folgenden Frameworks auditiert oder attestiert; die Zertifizierungsberichte sind unter NDA über den Support verfügbar: - SOC 2 Type II (jährlich) - ISO/IEC 27001 - DSGVO-konforme Kontrollen (EDPB-Leitlinien angewendet) - FADP-konforme Kontrollen für die Schweizer Region (revDSG) Geplant: HIPAA BAA (US-Enterprise-Kunden), zusätzliche regionale Attestierungen, wenn die Regionsliste wächst. ## Geteilte Verantwortung | Kontrolle | Tale | Du | Beleg | | ----------------------------- | ---------------------- | ----------------------- | ------------------------------------------------------------- | | Infrastruktur-Verfügbarkeit | ✓ | | Status-Seite, SOC 2 SLA-Bericht | | Datenverschlüsselung ruhend | ✓ | | Architektur-Beschreibung | | Verschlüsselung im Transit | ✓ | | TLS-Terminierung an Tales Edge | | Mitgliedsidentität und Rollen | | ✓ | [Mitglieder und Rollen](/de/platform/admin/members-and-roles) | | API-Key-Ausgabe und Rotation | | ✓ | [API-Keys](/de/platform/admin/api-keys) | | Content-Filterung und DLP | Stellt Hooks bereit | Konfiguriert Regeln | [Guardrails](/de/platform/admin/governance/guardrails) | | Audit-Log-Aufbewahrung | Stellt Speicher bereit | Setzt die Aufbewahrung | [Aufbewahrung](/de/self-hosted/configuration/retention) | | Auskunftsanfragen | Stellt Workflow bereit | Initiiert und genehmigt | [DSAR](/de/platform/admin/governance/data-subject-requests) | | Provider-Credentials | | ✓ | [Provider](/de/platform/admin/providers) | ## Datenschutz-Kontrollen Innerhalb des Produkts zählen drei Kontroll-Oberflächen für Compliance: - **Audit-Logs** — unveränderlicher Datensatz, wer was getan hat; Aufbewahrung konfigurierbar. - **Legal Hold** — nimmt eine Datensatz-Menge bis zur Aufhebung aus der Aufbewahrung; abgedeckt in [Legal Hold](/de/platform/admin/governance/legal-hold). - **Auskunftsanfragen** — der Anfrage-→-Übernahme-→-Löschung-→-Audit-Workflow; abgedeckt in [DSAR](/de/platform/admin/governance/data-subject-requests). ## Vorfälle melden Tales Sicherheitsvorfall-Kontakt ist `security@tale.dev`. Vermutete Schwachstellen-Offenlegung folgt der Responsible-Disclosure-Policy auf derselben E-Mail. Kundenseitige Sicherheits-Advisories werden auf der Status-Seite veröffentlicht und dem Owner der Org per E-Mail zugestellt. ## Wo das hineinpasst Trust und Compliance ist die Audit-Zeit-Seite; [Daten-Residenz](/de/cloud/data-residency) ist die Architektur-Zeit-Seite; [Subprozessoren](/de/legal/subprocessors) ist die Vendor-Listen-Seite. Ein Auditor will normalerweise alle drei zugleich — leg dir Lesezeichen für alle drei. Betreibst du self-hosted, sind die Kontrollen dieselben; was sich ändert, ist, wer die Infrastruktur darunter betreibt — siehe [Self-hosted-Übersicht](/de/self-hosted/overview). # Cloud Source: https://tale.dev/docs/de/cloud Tale Cloud ist die verwaltete Edition. Tale betreibt die Infrastruktur, deine Daten liegen in der Schweiz oder in der EU, und die einzige Betriebssorge deines Teams ist, das Produkt zu nutzen. Der Code ist identisch mit der selbst gehosteten Variante; der Unterschied liegt darin, wer ihn laufen hält. Dieser Abschnitt behandelt die Themen, die spezifisch für Cloud sind — Onboarding, Regionen und Datenresidenz, Abrechnung, die Compliance-Position, die du einem Auditor vorlegen kannst, und wie du auf selbst gehostet migrierst, wenn sich deine Anforderungen ändern. Jede andere Feature-Referenz lebt einen Reiter weiter unter Plattform — identisch unabhängig von der Edition. ## Seiten in diesem Abschnitt <CardGroup cols="2"> <Card title="Onboarding" icon="rocket" href="/de/cloud/onboarding"> Instanz anfordern, Org erstellen, ersten Modell-Anbieter konfigurieren, ersten Agent veröffentlichen. Etwa eine Stunde für einen Redakteur. </Card> <Card title="Datenresidenz" icon="map-pin" href="/de/cloud/data-residency"> Wo deine Daten liegen, welche Sub-Auftragsverarbeiter sie berühren und was sich ändert, wenn du die Region wechselst. </Card> <Card title="Abrechnung" icon="credit-card" href="/de/cloud/billing"> Pläne, Sitze, abrechenbare Komponenten, Budgets, und wo du die Rechnung findest. </Card> <Card title="Vertrauen und Compliance" icon="shield-check" href="/de/cloud/trust-and-compliance"> Die Zertifizierungen, die Tale mitbringt, die geteilte Verantwortung und was du als Nachweis vorlegen kannst. </Card> <Card title="Auf selbst gehostet migrieren" icon="server" href="/de/cloud/migrate-to-self-hosted"> Aus Cloud exportieren, selbst gehostete Instanz aufsetzen, importieren. </Card> </CardGroup> ## Wo das hingehört Cloud ist die Eingangstür; Plattform ist der Ort, an dem die eigentliche Arbeit stattfindet. Sobald deine Organisation eingeloggt ist und der erste Agent läuft, verbringt dein Team nahezu die gesamte Zeit auf den Plattform-Seiten, nicht hier. Die eine Seite, die sich bei jeder Änderung deiner Betriebslage erneut lesen lohnt, ist [Datenresidenz](/de/cloud/data-residency) — sie zeigt jedes externe System, das deine Daten kreuzen. # Abrechnung Source: https://tale.dev/docs/de/cloud/billing Abrechnung auf Cloud ist gemessen, nicht pro Sitz. Du zahlst für Tokens, die von Chats und Agents verbraucht werden, für Sprachminuten, Bildgenerierungen und Speicher; die Plattform selbst kommt mit der Org. Diese Seite führt eine Rechnungszeile durch, listet die gemessenen Komponenten und verweist auf die Budgetkontrollen, die Überraschungen verhindern. Die Rechnung kommt monatlich per E-Mail und ist auch im Produkt unter **Einstellungen > Abrechnung** sichtbar. Cloud rechnet in der Abrechnungswährung deiner Org ab, die bei der Anmeldung auf USD voreingestellt ist und vor dem ersten Rechnungslauf geändert werden kann. ## Eine durchgespielte Rechnungszeile Eine Zeile auf der Rechnung lautet `Models — Anthropic Claude Sonnet — 1.2M tokens — $4.32`. Tale hat sie aus dem Pro-Nachricht-Nutzungs-Ledger zusammengesetzt: jede Chat-Antwort speichert das genutzte Modell, die Token-Zahl und den Preis zur Rate, die beim Abschluss des Aufrufs aktiv war. Zeilen aggregieren pro Provider und Modell pro Abrechnungsperiode. Das Detail ist als CSV vom selben Bildschirm herunterladbar. ## Plan-Tiers Tale bietet zwei Tiers — **Community** und **Enterprise**. Community ist die selbstgehostete Open-Source-Edition; du betreibst sie auf deiner eigenen Infrastruktur, und das Abrechnungskonzept dieser Seite gilt dafür nicht. **Enterprise** ist der gemanagte Tier (Cloud oder Self-hosted) mit Support-SLA, Audit-Log-Aufbewahrungs-Kontrollen, SSO, AVV und Zugriff auf Regionen jenseits des Defaults. Der Tier beeinflusst feste Monatsgebühren und Feature-Gates, nicht Pro-Aufruf-Kosten; das gemessene Pricing für Tokens, Sprache und Speicher unten gilt für Enterprise auf Cloud. ## Gemessene Komponenten | Komponente | Einheit | Gezählt als | Wo zu sehen | | ------------- | -------------------- | ------------------------------------------------- | ----------------------------------------------------------------- | | Modelle | Tokens (rein + raus) | Pro Provider-Aufruf; Aufschlag auf Provider-Rate | [Nutzungs-Analyse](/de/platform/admin/governance/usage-analytics) | | Sprache (TTS) | Gesprochene Zeichen | Pro als Audio gerenderter Agent-Antwort | Nutzungs-Analyse | | Sprache (STT) | Audio-Sekunden | Pro vom User aufgenommener Nachricht | Nutzungs-Analyse | | Bilder | Generierungen | Pro vom Modell zurückgegebenem Bild | Nutzungs-Analyse | | Speicher | GB-Monat | Object-Store-Verbrauch über die Periode gemittelt | Abrechnungsseite | ## Budgets und Überschreitungen Setz Budgets unter [Policies and limits](/de/platform/admin/governance/policies-and-limits). Eine **Budget rule** deckelt monatliche Ausgaben pro User, pro Team, pro Rolle oder pro Org. Ein Budget zu treffen liest sich als klarer Toast — **Nutzungslimit erreicht** — und pausiert den betroffenen Bereich, bis das Budget angehoben oder die Periode umgedreht wird. Die Default-Vorrangordnung ist `user > team > role > default` — die spezifischste Regel gewinnt. Eine **Warning threshold (%)** auf derselben Regel emittiert eine Benachrichtigung, wenn die Nutzung die Schwelle überschreitet, ohne zu blockieren. Greif zur Warnung, wenn du wissen, aber nicht unterbrechen willst; greif zu harten Limits, wenn Überschreitungen ein Notfall sind. ## Wo Nutzung zu finden ist Die reichste Ansicht ist [Nutzungs-Analyse](/de/platform/admin/governance/usage-analytics) unter Governance — sie bricht die Nutzung nach **Top Assistants**, **Top Models**, **Top Voice Models** und **Per-User Usage** auf, alle nach Datumsbereich filterbar. Die Abrechnungsseite in den Einstellungen zeigt die Rechnungs-Ansicht; die Nutzungs-Analyse zeigt die operative Ansicht. ## Wo das hineinpasst Abrechnung ist die Schlagzeilenseite des Betreibers; [Nutzungs-Analyse](/de/platform/admin/governance/usage-analytics) ist die alltägliche. Sind die Kosten deiner Org hauptsächlich Tokens, ist die Top-Models-Tabelle die zu setzende Lesezeichen-Seite — sie zeigt, auf welche Modelle sich das Team festgelegt hat, und sagt dir, ob ein Wechsel zu einer billigeren Alternative etwas brächte. Für Self-hosted-User gilt das Abrechnungskonzept nicht (du zahlst deinen Provider direkt); die Kosten-Sichtbarkeitsseite schon. # Daten-Residenz Source: https://tale.dev/docs/de/cloud/data-residency Daten-Residenz auf Cloud beantwortet zwei Fragen, die jedes Audit am Ende stellt: welche Region hält deine Daten ruhend, und welche externen Systeme berühren sie im Fluss. Diese Seite verfolgt einen einzelnen Chat-Roundtrip von Anfang bis Ende, listet die Datenklassen und benennt jeden Sub-Prozessor, den deine Nachrichten passieren. Die Default-Region für neue Cloud-Orgs ist die Schweiz. Die Region nach der Anmeldung zu wechseln ist eine Migration, kein Setting-Flip — eine Org in der EU-Region neu zu erstellen ist schneller, als eine bestehende zu verschieben. Wähl einmal; wähl bewusst. ## Ein durchgespieltes Beispiel — ein Chat-Roundtrip Der User in Zürich öffnet Chat und sendet „fass den letzten Kundenanruf zusammen". Die Anfrage trifft Tales Edge in der gewählten Region, landet auf `tale-platform`, ruft in `tale-convex` (das Backend), liest das gebundene Wissen aus der Datenbank des Wissens-Korpus und emittiert einen ausgehenden Anruf an den Modell-Provider, gegen den der Agent konfiguriert ist. Der Wissens-Abruf läuft im Convex-Backend — es fragt die Korpus-Datenbank direkt ab, ohne separaten Retrieval-Dienst im Pfad. Der Modell-Provider gibt Tokens zurück; Tale streamt sie auf demselben Pfad zurück. Die Antwort und die Zitate landen in der operativen Datenbank, der Korpus bleibt in der Wissensdatenbank, und beide werden innerhalb der Region repliziert. Zwei Pfeile überqueren in diesem Trip die regionale Grenze: der Anruf an den Modell-Provider (immer extern) und jeder Sub-Prozessor, den die Tools des Agents ausgelöst haben (Web-Fetch, OneDrive-Lese, MCP-Server in einer anderen Region). Alles andere bleibt in der Region. ## Primärregionen | Region | Postgres | Object Store | DR-Replikat | | ----------------- | --------- | ------------ | ----------- | | Schweiz | Zürich | Zürich | Genf | | Europäische Union | Frankfurt | Frankfurt | Dublin | Das DR-Replikat ist für Disaster Recovery, nicht für aktiven Verkehr. Die Daten einer Region fliessen nie zum Primary oder Replikat der anderen Region. ## Was in der Region bleibt, was sie verlässt | Datentyp | Region-gebunden | Überquert | Hinweise | | -------------------------------- | --------------- | --------- | ------------------------------------------------------------------------------------ | | Chats und Nachrichten | ✓ | | | | Dokumente und Wissens-Embeddings | ✓ | | | | Org-Konfiguration und Rollen | ✓ | | | | Audit-Logs | ✓ | | | | Modell-Provider-Anfragen | | ✓ | Geht an den konfigurierten Provider; wähl einen regionalen Endpunkt, wenn vorhanden. | | OneDrive-Sync | | ✓ | Die Speicherregion von Microsoft gilt. | | Web-Tool-Abrufe | | ✓ | Wohin die URL auflöst. | ## Backups und DR Tale schnappt beide Postgres-Datenbanken — den operativen Speicher und den Wissens-Korpus — täglich und den Object Store stündlich. Schnappschüsse sind ruhend verschlüsselt mit Schlüsseln, die Tale hält; das DR-Replikat erhält eine Kopie innerhalb der Region. Restores aus Schnappschüssen sind eine kundeninitiierte Operation, geroutet über den Support; das SLA deckt die Restore-Zeit ab. ## Region wechseln Ein Regionswechsel ist als Export aus der aktuellen Region, Import in die neue Region und DNS-Cutover implementiert. Die Prozedur ist dieselbe wie [Auf Self-hosted migrieren](/de/cloud/migrate-to-self-hosted), ausser dass beide Seiten Cloud-Regionen sind; rechne mit Ausfallzeit im Minutenbereich und einem geplanten Fenster. Es gibt keinen In-place-Region-Schalter. ## Wo das hineinpasst Daten-Residenz ist die erste Seite, die jede Compliance-Prüfung liest. Paar sie mit [Trust und Compliance](/de/cloud/trust-and-compliance) (welches Framework deckt was) und [Subprozessoren](/de/legal/subprocessors) (die Liste jedes externen Systems, das oben benannt ist). Erwägt deine Org Self-hosted wegen einer Residenz-Anforderung, ist [Self-hosted-Übersicht](/de/self-hosted/overview) die nächste Lektüre — den Stack auf eigener Hardware zu laufen bewegt jeden Pfeil dieser Seite innerhalb deiner eigenen Grenze. # Auf Self-hosted migrieren Source: https://tale.dev/docs/de/cloud/migrate-to-self-hosted Die Migration von Cloud zu Self-hosted ist ein echtes Verfahren, kein Setting-Flip. Die Daten exportieren, die neue Instanz importieren, DNS schwenkt auf den neuen Host, und dein Team meldet sich in derselben Org an, die es hatte — dieselben Agents, dieselben Chats, dieselbe Audit-History. Dieses Tutorial führt das Verfahren und zeigt, wo es schiefgeht. Greif danach, wenn Self-hosting wirklich besser passt: Daten-Residenz erfordert Hardware unter deiner Kontrolle, Kosten im Massstab machen On-premise billiger als Pro-Token, oder die Org hat entschieden, den Stack selbst zu betreiben. Für die meisten Teams bleibt Cloud die richtige Wahl — lies [Cloud-Onboarding](/de/cloud/onboarding) noch einmal, wenn du noch entscheidest. ## Bevor du beginnst Hab diese Dinge vor dem Export bereit: - Einen Ziel-Host, der die Self-hosted-Voraussetzungen erfüllt — siehe [Quickstart](/de/self-hosted/install/quickstart) für die Spec. - DNS-Kontrolle über die Domain, die deine Org aktuell nutzt; du wirst sie beim Cutover schwenken. - Ein Wartungsfenster von mindestens einer Stunde. Der Import selbst ist schneller, aber DNS-Propagation und Validierung fügen Zeit hinzu. - Eine kürzliche Backup-Bestätigung im Audit-Log deiner Cloud-Org. Während einer Migration wird in der Quelle nichts gelöscht, aber das Export-Bundle ist dein Beleg, dass der Quellzustand konsistent war. ## Was mitkommt und was nicht Kommt mit: Chats, Threads, Nachrichten, Anhänge, Dokumente, Wissens-Embeddings, Agents, Agent-Versionen, Workflows, Executions, Audit-Logs, Mitglieder, Rollen, Teams, Branding, API-Keys, Integrations-Metadaten. Kommt nicht mit: externe Integrationen müssen gegen die neue Instanz neu authentifiziert werden (die Credentials leben im Provider, nicht im Export-Bundle); aktiv laufende Workflows pausieren und nehmen auf der neuen Instanz nach dem Cutover wieder auf; Sprach-Audios, die über das Aufbewahrungsfenster der Org hinaus aufbewahrt werden, bleiben im Cloud-Object-Store, bis sie geleert werden. ## Schritt 1 — Exportieren Öffne **Einstellungen > Organisation** auf Cloud und klick **Export**. Der Dialog führt den Export im Hintergrund aus und schickt einen Download-Link per E-Mail, wenn er fertig ist. Der Export ist ein einzelnes verschlüsseltes Bundle; die E-Mail enthält den Entschlüsselungs-Key. Lade das Bundle herunter und speichere den Key getrennt. ## Schritt 2 — Die Ziel-Instanz aufstellen Folg auf dem Ziel-Host [Quickstart](/de/self-hosted/install/quickstart) bis zum First-Admin-Schritt. Lad noch keine User ein — der Import überschreibt die Mitgliederliste. Bestätige, dass die neue Instanz bootet und du dich als Owner anmelden kannst. ## Schritt 3 — Importieren Melde dich auf der Ziel-Instanz als Owner an und besuche `/_internal/import` (verlinkt von der Einstellungsseite nach einer frischen Installation). Lad das Bundle hoch, füg den Entschlüsselungs-Key ein und klick **Import**. Der Import ist eine lang laufende Operation; die Seite zeigt Fortschritt pro Datenklasse. Löst sich die Seite zu **Import complete** auf, trägt die neue Instanz den vollen Zustand der Quell-Org. ## Schritt 4 — DNS schwenken Aktualisiere den DNS-Eintrag für die Domain der Org, sodass er auf die neue Instanz zeigt. Sobald die Propagation landet und das TLS der neuen Instanz gesund ist, landen User, die sich anmelden, auf der Self-hosted-Instanz mit ihren bestehenden Credentials. Die Cloud-Org wird an diesem Punkt nur-lesbar — um Drift zu vermeiden, archiv sie nach ein paar Tagen Vertrauen unter **Einstellungen > Organisation** auf Cloud. ## Fehlersuche - **Export hängt bei „preparing".** Sehr grosse Orgs (>100 GB) brauchen länger, als das E-Mail-Fenster annimmt. Öffne ein Support-Ticket; der Export läuft im Hintergrund bis zum Abschluss. - **Import scheitert an Schema-Mismatch.** Deine Ziel-Instanz läuft eine ältere Tale-Version als der Cloud-Export erwartet. Upgrade die Ziel-Instanz, bevor du es erneut versuchst — das Bundle ist vorwärts-kompatibel, nicht rückwärts-kompatibel. - **Mitglieder können sich nach dem Cutover nicht anmelden.** Session-Cookies sind auf den alten Host begrenzt. Mitglieder authentifizieren sich einmal neu; SSO- und 2FA-Einstellungen kommen mit. - **Workflows zeigen „pausiert" nach dem Import.** Erwartet — der Import bewahrt den Zustand, nimmt aber laufende Executions nicht automatisch wieder auf. Öffne jeden Workflow und klick **Resume**, nachdem du bestätigt hast, dass die Ziel-Instanz von externen Triggern erreichbar ist. ## Wo das eingesetzt wird Migration ist in der Praxis eine Einbahn-Operation — bist du einmal self-hosted, bleibst du es, ausser etwas ändert sich strukturell. Die umgekehrte Migration (Self-hosted zu Cloud) folgt derselben Form mit demselben Tooling und wird unterstützt, ist aber selten. Bist du noch auf Cloud und liest das für Kontext, ist die Anschluss-Seite [Self-hosted-Übersicht](/de/self-hosted/overview); sie benennt, was du dir aufhalst. # Cloud-Onboarding Source: https://tale.dev/docs/de/cloud/onboarding <!-- Internal, for agents editing this page: Tale Cloud has no self-serve sign-up — tale.dev ships no sign-up route. A Cloud customer fills in the demo request form (https://tale.dev/request-demo — /de/ and /fr/ localized), and the Tale team sets up a dedicated demo instance for them. The journey below only starts once that instance exists; from there it deliberately mirrors normal first-run onboarding (sign-up on the customer's own instance, org wizard, providers). Keep the request-your-instance step first and do not change the entry point back to a tale.dev sign-up. --> Diese Strecke führt von der Demo-Anfrage zu einer produktionsreifen Cloud-Org mit einem funktionierenden Agent. Das Ergebnis ist eine Org, in der sich dein Team anmelden, einen funktionierenden Agent wählen und ihn etwas Nützliches fragen kann — noch nichts Aufregendes, nur das Fundament, auf dem alles Weitere aufbaut. Du brauchst eine funktionierende E-Mail-Adresse und die Möglichkeit, sie zu verifizieren. Die Strecke setzt kein Tale-Vorwissen voraus; referenziert unten etwas ein Konzept, das du noch nicht kennst, führt die verlinkte Seite es ein. Sobald deine Instanz bereitsteht, dauert der praktische Teil unter einer Stunde — rund die Hälfte davon steckt im Anbieter-Schritt, der Rest ist überwiegend Klicken. ## Bevor du beginnst Klär drei Dinge: - Eine E-Mail-Adresse für den ersten Inhaber der Org. Dieses Konto trägt die höchste Rolle; wähl jemanden, der nicht nächste Woche das Team verlässt. - API-Zugangsdaten für mindestens einen Modellanbieter (OpenAI, Anthropic, Azure oder ein kompatibler lokaler). Das Portal des Anbieters zeigt, wo sie liegen. - Die Region, in der deine Daten liegen sollen. Cloud bietet die Schweiz und die EU; die Wahl gehört zum Instanz-Setup — ein späterer Wechsel ist eine echte Migration. ## Von der Demo-Anfrage zum funktionierenden Agent <Steps> <Step title="Fordere deine Instanz an"> Tale Cloud ist kein Self-Service — jede Cloud-Org läuft auf einer eigenen Instanz, die das Tale-Team für dich aufsetzt. Füll das Demo-Formular unter [tale.dev/de/request-demo](https://tale.dev/de/request-demo) aus; Name und E-Mail genügen, Firma und ein Satz dazu, was deine Agenten tun sollen, helfen dem Team, das Setup zuzuschneiden. Das Team setzt dann deine eigene Demo-Instanz auf — eine dedizierte Umgebung, keine geteilte Testumgebung — und meldet sich, sobald sie bereitsteht. </Step> <Step title="Erstelle deine Organisation"> Öffne deine Instanz und registriere dich. Das Formular fragt nach Name, E-Mail und Passwort; bestätige den E-Mail-Link, sobald er ankommt. Der nächste Bildschirm fragt eine Sache ab: **Organisationsname** — der Anzeigename, den dein Team in der Ecke jeder Seite sieht. Wähl einen, der ein Rebranding überlebt. <Frame caption="Der Arbeitsbereichs-Schritt — der Name, den dein Team überall sieht."> ![Der Assistent zum Erstellen einer Organisation auf seinem Arbeitsbereichs-Schritt, mit Northlight Labs im Feld Organisationsname und aktivem Knopf Weiter.](/images/get-started/org-create-wizard.webp) </Frame> Der erste Benutzer wird automatisch **Inhaber** der Org. Falls du es vergisst: Deine Rolle siehst du später im Abschnitt **Mitglieder** unter **Einstellungen > Organisation**. </Step> <Step title="Lade den ersten Admin ein"> Öffne **Einstellungen > Organisation**, scroll zum Abschnitt **Mitglieder** und klicke auf **Mitglied hinzufügen**. Gib die E-Mail des Admins ein und weise die Rolle **Admin** zu. Die eingeladene Person erhält eine E-Mail mit einem Magic-Link, registriert sich und landet in der Org mit der zugewiesenen Rolle. Die Sicherheitsregel „mindestens 2 Admins" verhindert, dass sich eine Org versehentlich aussperrt, indem sie ihren einzigen Admin entfernt — lad einen zweiten Admin ein, bevor du etwas tust, das sie voraussetzt. Die Rollen-Matrix (wer was darf) steht in [Mitglieder und Rollen](/de/platform/admin/members-and-roles). </Step> <Step title="Verbinde einen Modellanbieter"> Öffne **Einstellungen > KI-Anbieter** und klicke auf **Anbieter hinzufügen**. Wähl den Anbieter, für den du Zugangsdaten hast, und füg den API-Schlüssel ein. Speichere. Tale validiert den Schlüssel im Hintergrund; eine Bestätigung auf der Anbieterzeile heißt, dass er funktioniert. Schlägt die Validierung fehl, zeigt die Zeile den Fehler wörtlich — die häufigste Ursache ist Whitespace um den Schlüssel. <Frame caption="Der verbundene Anbieter — von hier kann jeder Agent antworten."> ![Die Einstellungsseite für KI-Anbieter listet einen verbundenen Anbieter, OpenRouter, mit seiner Basis-URL und 52 Modellen.](/images/get-started/settings-providers.webp) </Frame> <Note> An diesem Schritt stocken die meisten Onboarding-Sitzungen — das Anbieter-Portal ist meist ein anderes Login, und das Team muss nach dem Schlüssel graben. Hängt die Validierung länger als eine Minute, lade die Seite neu; der Schlüssel ist gespeichert, sobald **Speichern** bestätigt — die Zeile braucht manchmal ein Neuladen, um ihn anzuzeigen. </Note> </Step> <Step title="Veröffentliche deinen ersten Agent"> Öffne **Agenten** und klicke auf **Agent erstellen**. Wähl das gerade verbundene Modell. Schreib einen Absatz Anweisungen — die Stimme, in der der Agent antworten soll, die Domäne, die er kennt, die Fälle, die er ablehnt. Speichere. Schalte **Im Chat sichtbar** ein. Der Agent ist jetzt aus jedem Chat in der Org erreichbar. Was einen Agent gut macht, vertieft [Einen Agent erstellen](/de/platform/agents/create). </Step> <Step title="Öffne den Chat"> Klicke in der Sidebar auf **Neuer Chat**. Wähl den Agent in der Auswahl, tippe eine Frage aus seiner Domäne, sende. <Check> Die Antwort streamt zurück — landet sie so, wie du die Anweisungen geschrieben hast, ist die Org mit dem Onboarding fertig. </Check> Drei Anschlussaufgaben, die sich jetzt lohnen, solange alles frisch ist: - Öffne **Einstellungen > Branding** und lade das Org-Logo hoch. - Setz die Standardsprache der Org unter **Einstellungen > Organisation**. - Überflieg [Trust und Compliance](/de/cloud/trust-and-compliance), damit du weißt, was du einem Auditor zeigst, bevor einer fragt. </Step> </Steps> ## Fehlersuche - **Die Einladungs-E-Mail kommt nie an.** Schau im Spam-Ordner der eingeladenen Person nach. Tale sendet von `noreply@tale.dev`; manche Unternehmensfilter halten das zurück. - **Die Anbieter-Validierung scheitert mit „invalid key".** Kopier den Schlüssel erneut aus dem Anbieter-Portal — beim Kopieren landet oft ein führendes oder folgendes Leerzeichen mit. - **Der Agent taucht nicht in der Chat-Auswahl auf.** Prüfe, dass **Im Chat sichtbar** für den Agent eingeschaltet ist. ## Wo das eingesetzt wird Du hast jetzt eine Org mit einem funktionierenden Agent und einem Admin neben dir. Die natürliche nächste Strecke ist [Deinen ersten Agent bauen](/de/tutorials/editor/first-agent-end-to-end) — dieselbe Form, aber mit einem Agent, der über Wissensanbindungen echte Domänenarbeit leistet. Bist du hier, um Cloud gegen selbst gehostet abzuwägen, ist [Auf Self-hosted migrieren](/de/cloud/migrate-to-self-hosted) die Strecke in die Gegenrichtung. # Automatisations livrées Source: https://tale.dev/docs/fr/platform/automations/builtin Tale livre des automatisations prêtes à l’emploi : trois à but unique qui transforment une boîte aux lettres en une boîte de réception partagée, et un bundle qui résout les issues GitHub de bout en bout. Les Éditeurs et Membres se servent de ce qu’une automatisation installée ajoute — un onglet Boîte de réception, une entrée de Backlog — sans rien installer eux-mêmes ; installer est une action Propriétaire/Admin/Développeur couverte sur [Parcourir et installer des automatisations](/fr/platform/automations/catalog). Cette page nomme ce que fait chacune et l’intégration qu’il faut connecter en premier. <Frame caption="Le catalogue des automatisations — chaque carte est à une installation près ; les membres de packs cachés et l’intérieur des bundles restent hors de la liste."> ![Le catalogue des automatisations sur l’onglet Toutes les automatisations, avec les cartes des automatisations e-mail et du bundle Résoudre les issues GitHub, chacune avec son icône et sa description.](/images/platform/automations-catalog.webp) </Frame> ## Synchroniser les e-mails Gmail, Outlook et IMAP **Synchroniser les e-mails Gmail**, **Synchroniser les e-mails Outlook** et **Synchroniser les e-mails via SMTP/IMAP** sont la même automatisation répétée trois fois, une par type de boîte aux lettres : chacune requiert exactement l’intégration que son nom indique, chacune installe la même vue intégrée **Boîte de réception**, indépendante du canal, et chacune embarque le workflow de synchronisation qui rapatrie la boîte aux lettres dans les conversations selon une planification (toutes les six heures d’origine — resserrable sur l’onglet **Déclencheurs** de l’automatisation). Une organisation qui reçoit du courrier sur plus d’un type de boîte aux lettres en installe plusieurs ; chaque Boîte de réception ne montre que le trafic de sa propre boîte aux lettres. | Automatisation | Requiert | Boîte aux lettres | | -------------------------------------- | --------- | --------------------------------- | | Synchroniser les e-mails Gmail | Gmail | Une boîte Gmail | | Synchroniser les e-mails Outlook | Outlook | Une boîte Microsoft Outlook | | Synchroniser les e-mails via SMTP/IMAP | IMAP/SMTP | Toute boîte privée en IMAP / SMTP | ## L’onglet Boîte de réception Chacune des trois s’ouvre sur son onglet **Boîte de réception** : quatre sous-onglets — **Ouvert**, **Fermé**, **Spam**, **Archivé** — chacun une vue scindée avec la liste des conversations à gauche et le fil sélectionné à droite. Ouvrir une conversation remplit le panneau de droite avec tout l’historique de ses messages ; tant que tu n’en as choisi aucune, le panneau affiche **Sélectionne une conversation pour voir les détails**. Le compositeur se trouve sous le fil dans l’onglet **Ouvert** — les réponses appartiennent aux conversations actives, donc les trois autres onglets sont en lecture seule. Écris dans **Saisis un message** et clique sur **Envoyer** ; la réponse part par la boîte aux lettres sur laquelle la conversation est arrivée, avec le destinataire et l’objet dérivés du fil — rien à adresser à la main. **Améliorer** réécrit ton brouillon avec l’IA avant l’envoi. Sur l’automatisation IMAP, les réponses envoyées depuis la boîte elle-même — depuis n’importe quel client mail — se synchronisent aussi dans la conversation, ordonnées avec le reste du fil. L’en-tête du fil porte les verbes de statut de la conversation sélectionnée — **Fermer la conversation** et **Marquer comme spam** sur un fil ouvert, **Rouvrir la conversation** sur un fil fermé ou archivé, **Pas du spam** et le destructeur **Supprimer** sur le spam. Sélectionner plusieurs lignes dans la liste fait apparaître les mêmes verbes en actions groupées. ## Résoudre les issues GitHub **Résoudre les issues GitHub** est un bundle, pas une automatisation seule : l’installer lance un seul assistant agrégé qui installe quatre automatisations cachées d’un coup, liées au projet que tu choisis, et requiert l’intégration GitHub. Chaque membre couvre une étape de la boucle. **Trier les issues GitHub** — « Évalue les issues GitHub ouvertes d’un dépôt et propose les issues exploitables dans le backlog du projet — un humain les démarre depuis là. » — tourne sur une planification récurrente. **Synchroniser les issues GitHub** — « Termine une tâche du tableau lorsque son issue GitHub est fermée. Parcourt les tâches ouvertes du tableau lui-même, sans jamais en manquer. Mise à jour uniquement — ne crée jamais de tâche. » — que la fermeture vienne de la chaîne de résolution ou d’un humain agissant directement sur GitHub, le résultat est le même : jamais de création, jamais de réouverture. **Créer des pull requests GitHub** livre l’agent PR Creator : une fois qu’un humain a cliqué **Démarrer** sur une tâche proposée, il clone le dépôt, ouvre ou reprend la pull request de l’issue, implémente le correctif, le vérifie contre les tests du projet, et attend que la CI passe au vert. **Examiner les pull requests GitHub** livre l’agent PR Reviewer : il reteste la branche du PR Creator, confirme la CI, et un juge sans outils décide de la fusionnabilité — approuvé gare la tâche en **En revue** pour qu’un humain la fusionne sur GitHub ; non approuvé la renvoie au PR Creator avec un retour, jusqu’à un petit plafond de reprises. Un humain reste dans la boucle à deux moments : démarrer une tâche proposée depuis le Backlog, et fusionner la pull request sur GitHub lui-même — rien dans le bundle ne fusionne à ta place. ## Modèles de synchronisation et d’entretien Huit automatisations de plus attendent dans le catalogue pour le moment où tu en as besoin. Chacune est un workflow unique : installe-la, pointe-la vers tes données — les modèles de synchronisation demandent leur source via la planification qu’ils créent — puis ajuste-la librement sur l’onglet **Éditeur** de l’automatisation. | Automatisation | Requiert | Ce qu’elle fait | | ------------------------------------------ | ------------ | -------------------------------------------------------------------------------------------------- | | Synchroniser les pages Confluence | Confluence | Importe les pages d’un espace Confluence dans la bibliothèque de connaissances selon un planning | | Synchroniser les fichiers Google Drive | Google Drive | Importe les documents d’un dossier Drive dans la bibliothèque de connaissances | | Synchroniser les clients Shopify | Shopify | Importe les clients de la boutique dans les fiches clients de l’organisation | | Synchroniser les produits Shopify | Shopify | Importe le catalogue produits de la boutique dans les fiches produits de l’organisation | | Analyser les relations entre produits | — | Parcourt le catalogue et consigne accessoires, variantes et compléments | | Indexer les documents pour la recherche | — | Indexe les documents fraîchement importés pour que les agents puissent les rechercher et les citer | | Archiver les conversations inactives | — | Clôt les conversations restées silencieuses au-delà de leur période d’inactivité | | Notifier les membres des messages entrants | — | Alerte les membres dès qu’un nouveau message entrant arrive dans une conversation ouverte | ## Les packs préinstallés La mécanique qui fait tourner les tableaux de chaque organisation est elle aussi faite d’automatisations — installées automatiquement à la création, cachées du catalogue, mais visibles sur l’onglet **Installées** comme tout le reste. Le **pack tâches** lance un agent assigné dès qu’une tâche lui arrive, trie le travail non assigné, réagit aux @-mentions, fait passer le travail terminé par la relecture, balaie les exécutions bloquées, fait respecter les SLA et garde en mouvement tâches dépendantes, sous-tâches et archives ; ses voisins répondent aux mentions en discussion et gardent les fichiers OneDrive synchronisés. Chacune est une automatisation normale — ouvre-la pour lire son workflow sur l’onglet **Éditeur**, l’observer sous **Exécutions** ou couper un déclencheur sous **Déclencheurs** ; une désinstallation tient, et rien ne la réinstalle dans ton dos. ## Où cela s’inscrit Les automatisations de boîte de réception, le bundle Résoudre les issues GitHub et les modèles de synchronisation sont ce qui est livré aujourd’hui ; une automatisation privée que ton organisation construit ou téléverse apparaît dans le même catalogue, juste à côté. [Parcourir et installer des automatisations](/fr/platform/automations/catalog) couvre la mécanique du catalogue ; [Backlog du projet](/fr/platform/projects/backlog) est la lecture suivante pour ce qui arrive à une tâche une fois que Trier les issues GitHub l’a proposée. # Concepts d’automatisation Source: https://tale.dev/docs/fr/platform/automations/concepts Une automatisation est l’unité vers laquelle Tale se tourne quand un travail a besoin de plus d’une pièce mobile assemblée à la main — une connexion d’intégration, un ou plusieurs agents, un workflow, parfois une page à elle — et que tu veux tout ça installé et branché en une seule action. Les Propriétaires, Admins et Développeurs installent les automatisations depuis le catalogue Automatisations ; une fois installée, les Éditeurs et Membres se servent de ce qu’elle a livré — un onglet Boîte de réception, une entrée de Backlog, un agent de chat — sans avoir besoin de savoir ce qu’il y a dessous. Cette page nomme les pièces qu’une automatisation empaquette, le workflow qui la fait tourner, et quand une automatisation est la bonne unité plutôt qu’un agent seul. ## Ce qu’une automatisation empaquette Le manifeste d’une automatisation nomme jusqu’à cinq types de pièces, et la plupart des automatisations n’en utilisent que quelques-unes. **Intégrations** sont les identifiants que ses étapes et ses agents appellent — Gmail, GitHub, une base de données SQL. Une automatisation ne stocke jamais sa propre copie d’un identifiant ; elle nomme l’intégration dont elle a besoin, et l’organisation connecte cette intégration une fois, la même connexion que partagent toutes les autres automatisations et tous les agents. **Agents** sont les agents de chat ou de tâche que l’automatisation installe — un trieur, un relecteur de pull requests, un résumeur. Une fois installés, ce sont des agents ordinaires : mentionnables dans le chat, assignables sur un tableau de projet, modifiables dans l’éditeur d’agent. **Un workflow** est la définition unique déclencheur-plus-étapes que l’automatisation embarque — ce qui tourne réellement sur une planification, un webhook ou un clic manuel. Toutes les automatisations n’en livrent pas une : les automatisations e-mail couvertes sur [Automatisations livrées](/fr/platform/automations/builtin) n’en ont aucune, parce que lire et répondre au courrier est une page, pas une exécution planifiée. **Vues intégrées** sont des pages que l’automatisation enregistre dans le registre de vues partagé de la plateforme, comme la Boîte de réception — la plateforme rend la page elle-même ; l’automatisation ne fait que nommer laquelle et ce sur quoi elle porte. **Configuration** n’est pas un fichier de réglages séparé. Une automatisation qui a besoin d’une valeur d’opérateur la lit depuis l’identifiant d’une intégration ou depuis une variable de déclencheur ou de nœud d’un workflow ; l’onglet Configuration de l’automatisation est un résumé en lecture seule des pièces ci-dessus, pas un endroit où ajouter de nouveaux réglages. ## Le workflow à l’intérieur Il n’existe pas de surface de workflow autonome dans Tale — un workflow vit et s’exécute dans son automatisation, et l’onglet **Éditeur** de celle-ci est l’endroit où tu le rencontres. La définition est un graphe d’étapes typées : les étapes **LLM** appellent un agent ou un modèle, les étapes **Action** font du travail concret comme appeler une intégration ou créer et mettre à jour des tâches sur le tableau du projet, les étapes **Condition** aiguillent le graphe sur un oui ou un non, les étapes **Boucle** répètent sur un ensemble, et les étapes **Sandbox** exécutent du code. Chaque enregistrement fige une version que tu peux restaurer depuis **Historique**. [L’éditeur de workflow](/fr/platform/automations/editor) est le manuel d’exploitation de cette surface. Les **déclencheurs** décident quand le workflow s’exécute. Trois sortes s’attachent sur l’onglet **Déclencheurs** : les **Planifications** (cron), les **Webhooks** (un POST externe) et les **Événements** (quelque chose se produit dans Tale, comme `task.created`) — et tu peux toujours lancer une exécution à la main depuis le panneau **Tester le workflow** de l’éditeur. La [référence des déclencheurs](/fr/platform/automations/triggers) couvre chaque sorte. Les **exécutions** sont l’historique. Chaque exécution écrit un enregistrement — statut, chronologie, l’entrée reçue et un journal par étape de ce que chaque étape a consommé et produit. L’onglet **Exécutions** est la piste d’audit et la surface de débogage en un seul endroit ; [Journaux d’exécution](/fr/platform/automations/execution-logs) en lit un de bout en bout. ## Là où les humains interviennent Les automatisations tournent sans toi, mais elles ne changent et ne démarrent qu’avec toi : les modifications que l’éditeur IA propose sur un workflow arrivent comme cartes d’approbation avant de s’appliquer, un agent qui veut exécuter un workflow a d’abord besoin de ton approbation, et une exécution qui attend une réponse se met en pause avec le statut **En attente de saisie**. [Approbations dans les workflows](/fr/platform/automations/approvals-in-workflows) couvre les trois. Une boucle qui repasse par le même portail de revue — une tâche renvoyée pour une passe de plus — ouvre une nouvelle demande à chaque tour plutôt que de réutiliser la carte déjà résolue. ## Bundles et automatisations cachées Un bundle regroupe plusieurs automatisations qui n’ont de sens qu’installées ensemble. **[Résoudre les issues GitHub](/fr/platform/automations/builtin)** installe quatre automatisations — un trieur, un synchroniseur, un créateur de pull requests et un relecteur de pull requests — via un seul assistant d’installation agrégé, lié au projet que tu choisis. La plupart des membres d’un bundle sont cachés : ils n’apparaissent jamais comme leur propre carte dans le catalogue, parce qu’installer l’un d’eux seul n’aurait aucun sens sans ses frères. Caché ne veut pas dire disparu — l’[Assistant d’automatisation](/fr/platform/automations/assistant) peut toujours les trouver et les expliquer ; seule la grille du catalogue les masque. ## Mis bout à bout — deux combinaisons **Synchroniser les e-mails Gmail** combine le plus petit ensemble possible : une intégration (Gmail) et une vue intégrée (Boîte de réception) — pas d’agent, pas de workflow. Connecte Gmail, et l’onglet Boîte de réception est toute l’automatisation. **Résoudre les issues GitHub** combine toutes les pièces à la fois : une intégration (GitHub), quatre agents répartis sur ses quatre membres cachés, quatre workflows, et aucune vue intégrée — elle passe par le Tableau et le Backlog déjà existants du projet plutôt que par une page à elle. Installer le bundle branche les quatre en un seul assistant agrégé, lié au projet que tu choisis. ## Quand y recourir | Utilise … quand | Automatisation | Agent | Webhook d’agent | | ----------------------------------------------------------------------------- | -------------- | ----- | --------------- | | Tu veux une fonctionnalité déjà intégrée, installée en une action | ✓ | | | | Le travail a plusieurs étapes, des branches, des planifications ou des revues | ✓ | | | | La même question revient dans le chat, sans système externe en jeu | | ✓ | | | Une réponse d’agent par POST entrant suffit | | | ✓ | Vérifie le catalogue avant de construire quoi que ce soit — l’automatisation dont tu as besoin est peut-être déjà livrée. Quand rien de livré ne convient, tu construis quand même une automatisation : décris le workflow à l’[éditeur IA](/fr/platform/automations/editor) ou téléverse un paquet, plutôt que d’assembler des pièces détachées. Un [webhook d’agent](/fr/platform/agents/webhook-triggers) est la seule couture hors de ce modèle — recours-y quand une seule réponse d’agent par message entrant suffit au travail. ## Construis-en une Une automatisation est le bundle complet dont une fonctionnalité réelle a besoin — l’intégration qu’elle appelle, les agents qui font le travail, le workflow qui l’exécute, la vue qu’elle affiche — branchés ensemble et installés en une action, avec la mécanique d’exécution du workflow (déclencheurs, exécutions, approbations) sur les onglets de l’automatisation elle-même. La lecture suivante naturelle est [Parcourir et installer des automatisations](/fr/platform/automations/catalog) — elle parcourt le catalogue, le panneau latéral et l’assistant d’installation de bout en bout ; [L’éditeur de workflow](/fr/platform/automations/editor) prend le relais pour la surface où le moteur de l’automatisation se construit et s’ajuste. # Journaux d’exécution Source: https://tale.dev/docs/fr/platform/automations/execution-logs Les journaux d’exécution sont l’historique d’un seul workflow. Chaque fois qu’un déclencheur se lance, Tale ouvre un enregistrement d’exécution et y écrit au fil de l’exécution — statut, chronologie, l’entrée reçue et ce que chaque étape a consommé et produit. L’onglet **Exécutions** est la surface de débogage vers laquelle chaque autre page des automatisations pointe quand quelque chose a mal tourné. <Frame caption="L’onglet Exécutions — une ligne par exécution ; le seul badge rouge au milieu des verts est le point de départ d’une session de débogage."> ![L’onglet Exécutions d’une automatisation listant douze exécutions — onze avec un badge vert Terminé et une avec un badge rouge Échoué — chacune avec un ID d’exécution, un horodatage de départ, une durée et event comme source de déclenchement.](/images/platform/automation-executions.webp) </Frame> ## La vue liste Une ligne par exécution, la plus récente en premier. La barre d’outils porte **Rechercher par ID d'exécution**, un **Filtre** et un sélecteur de plage de dates. | Colonne | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ID d’exécution | Identifiant stable de l’exécution — l’icône de copie le met dans le presse-papiers. | | Statut | **En attente**, **En cours**, **Terminée** ou **Échouée** — plus **En attente de saisie** quand une exécution est bloquée sur un humain, et **En pause** pendant un débogage pas à pas. | | Démarrée le | Heure de départ, montre en main, à la milliseconde. | | Durée | Du départ à la fin ; vide tant que l’exécution est en cours. | | Déclenchée par | Le chemin qui a démarré l’exécution — une planification, un webhook, un événement ou un test depuis l’éditeur. | ## L’exécution dépliée Déplie une ligne et l’enregistrement s’affiche en JSON : les métadonnées d’exécution (statut, chronologie, source de déclenchement et l’erreur s’il y en a une), les métadonnées portées par le déclencheur, les variables d’entrée et le **journal** — une entrée par étape exécutée avec ses entrées, ses sorties et son statut. Une étape échouée porte la chaîne d’erreur qui l’a tuée. Lis le journal de haut en bas et l’exécution se raconte à nouveau ; l’entrée dont le statut bascule est l’étape qui s’est mal comportée. ## Nouvelles tentatives et relances Les échecs transitoires se retentent tout seuls. L’onglet **Configuration** du workflow fixe le défaut — **Nombre max de tentatives** et **Backoff (ms)** — et chaque étape peut le surcharger dans sa propre config. <Frame caption="L’onglet Configuration — le budget de tentatives et le backoff dont chaque étape hérite sauf si elle les surcharge."> ![L’onglet Configuration d’une automatisation montrant des champs de nom et de description, un timeout de 600000 millisecondes, un nombre max de tentatives de 3, un backoff de 1000 millisecondes et un éditeur JSON de variables.](/images/platform/automation-configuration.webp) </Frame> Une exécution qui échoue au-delà de son budget de tentatives reste **Échouée** pour la piste d’audit ; pour réessayer, ouvre **Tester le workflow** dans l’éditeur, colle l’entrée copiée depuis le bloc de variables de l’exécution échouée et clique sur **Exécuter**. La relance est une exécution neuve avec son propre ID. ## Une session de débogage de bout en bout Un rapport quotidien n’est pas arrivé. Ouvre le workflow, passe sur **Exécutions** et filtre sur les échecs du jour — l’exécution fautive est en haut. Déplie-la : le journal montre que l’étape de synthèse a échoué sur un timeout, et ses entrées portent le prompt reçu. Corrige la cause, relance depuis le panneau de test avec la même entrée, et regarde la nouvelle exécution se terminer avant de faire confiance à la planification de demain. ## Où cela s’inscrit Les journaux d’exécution sont le reçu que chaque workflow laisse derrière lui. Associe-les aux [déclencheurs](/fr/platform/automations/triggers) pour le coup d’envoi qui a ouvert chaque enregistrement, et aux [journaux d’audit](/fr/platform/admin/governance/audit-logs) pour la trace à l’échelle de l’org de qui a changé quoi. # Assistant d’automatisation Source: https://tale.dev/docs/fr/platform/automations/assistant L’**Assistant d’automatisation** est l’agent de chat épinglé à l’automatisation que tu as ouverte — clique sur **Assistant** sur la page d’une automatisation, et il répond avec déjà en contexte les agents, le workflow, les compétences, les intégrations et la configuration de cette automatisation. Les Admins et Développeurs s’en servent pour comprendre une automatisation qu’ils ne connaissent pas, en étendre une plutôt que la dupliquer, ou se faire aider à construire les pièces que la page de l’automatisation ne modifie pas directement. C’est le même agent assistant qu’embarque l’[éditeur de workflow](/fr/platform/automations/editor), donc une conversation démarrée depuis l’une des deux surfaces se lit familièrement depuis l’autre. ## Ce qu’il modifie directement Les workflows sont la seule pièce à laquelle l’assistant a un accès outil complet : il lit la définition courante, modifie les étapes, sauvegarde une nouvelle version et la fait tourner — exactement comme si tu étais passé par l’éditeur toi-même. Les agents viennent juste après : il lit le roster et peut en installer, activer ou désactiver un, mais les instructions, le modèle et le reste de la configuration d’un agent restent à modifier par toi dans l’éditeur d’agent ; l’assistant rédige le JSON exact et tu le colles. ## Ce qu’il rédige à ta place Les compétences, intégrations, vues intégrées et la configuration de l’automatisation n’ont aucun outil d’édition : l’assistant écrit la définition selon la compétence d’écriture ou d’intégration correspondante et te dit exactement où l’appliquer — Paramètres > Intégrations pour un identifiant, la page de l’automatisation elle-même pour une vue ou sa configuration. Installer et configurer fonctionnent pareil : il parcourt la checklist de préparation — connecter ce qui est requis, remplir la configuration, activer les agents et le workflow — plutôt que de faire la connexion lui-même. ## Trouver ce qui existe déjà Avant de construire quoi que ce soit, l’assistant cherche une automatisation ou un bundle à étendre plutôt qu’à dupliquer — la même règle de réutilisation d’abord que toute compétence d’écriture impose. Sa recherche atteint des automatisations que le catalogue lui-même cache : les membres cachés d’un bundle (voir [Concepts d’automatisation](/fr/platform/automations/concepts)) restent visibles pour l’assistant, qui peut donc te pointer vers, disons, l’agent PR Creator enfoui dans Résoudre les issues GitHub plutôt que d’en proposer un nouveau. ## Où cela s’inscrit L’Assistant d’automatisation est le chemin le plus rapide vers une automatisation que tu n’as pas construite toi-même — demande-lui ce que fait quelque chose avant d’y toucher à la main. [Concepts d’automatisation](/fr/platform/automations/concepts) est le vocabulaire qu’il présuppose ; [Parcourir et installer des automatisations](/fr/platform/automations/catalog) est l’endroit où agir sur ce qu’il te dit si l’automatisation n’est pas encore installée. # Déclencheurs de workflow Source: https://tale.dev/docs/fr/platform/automations/triggers Un déclencheur est ce qui démarre un workflow sans qu’un humain clique quoi que ce soit. L’onglet **Déclencheurs** d’un workflow porte trois sections — **Planifications**, **Webhooks** et **Événements** — et un workflow peut tenir plusieurs déclencheurs de n’importe quel mélange ; tous alimentent la même première étape. Un workflow sans déclencheur s’exécute toujours à la main depuis le panneau **Tester le workflow** de l’éditeur — utile pendant la construction, jamais pour la production. <Frame caption="L’onglet Déclencheurs avec la section Événements dépliée — un déclencheur d’événement, sa bascule Actif et son heure de dernier déclenchement."> ![L’onglet Déclencheurs d’une automatisation montrant les sections Planifications et Webhooks repliées et une section Événements dépliée avec une ligne de déclencheur task.created.](/images/platform/automation-triggers.webp) </Frame> ## Planifications Clique sur **Ajouter une planification** pour exécuter le workflow sur une horloge. Le formulaire prend une expression cron standard à 5 champs, avec des préréglages de **Toutes les 5 minutes** à **Tous les mois** — ou décris le rythme en langage courant et clique sur **Générer** pour laisser l’IA écrire le cron à ta place. Le **Fuseau horaire** fixe la zone dans laquelle le cron se déclenche, par défaut ton propre fuseau de navigateur ; modifier une planification existante conserve le fuseau qu’elle utilise déjà. Les **Variables du workflow** sont l’entrée que chaque exécution planifiée reçoit — et quand l’étape de démarrage du workflow déclare un schéma d’entrée, la boîte de dialogue l’affiche comme un vrai formulaire plutôt qu’en JSON brut : un champ `projectId` devient une liste déroulante **Projet** qui pointe par défaut vers le projet propre à cette planification, `owner` et `repo` se regroupent en un seul champ **Repository GitHub** qui accepte `owner/repo` ou une URL GitHub complète, et chaque autre champ déclaré reçoit son propre champ étiqueté avec la description du schéma comme aide. Un champ requis laissé vide affiche sa propre erreur et bloque **Enregistrer** — la même règle que le panneau **Tester le workflow** de l’éditeur applique déjà, pour qu’une planification ne puisse pas être enregistrée dans un état que son propre workflow rejetterait à l’exécution. Clique sur **Modifier en JSON** pour revenir à l’éditeur brut sur un schéma que le formulaire ne peut pas représenter. Ces variables sont propres à chaque planification, pas les valeurs par défaut du workflow affichées dans l’onglet **Configuration** de l’automatisation — deux planifications différentes du même workflow peuvent chacune envoyer leur propre dépôt ou projet, et seul ce qui est défini ici atteint l’exécution. La ligne montre le **Projet** lié de la planification (ou **Sans projet**), l’heure de **Dernier déclenchement** et qui l’a créée. Une planification à qui il manque encore une variable requise de son workflow porte un badge jaune **Configuration requise** — survole-le pour voir les noms de champs exacts — même active, car une exécution au déclenchement avec une valeur requise vide échoue ; une planification liée à un projet satisfait déjà une variable requise `projectId` sans avoir à la répéter dans les variables. Le même manque ressort aussi sur la bannière **Terminer la configuration** propre à l’automatisation et sur l’étape Terminé de l’[assistant d’installation](/fr/platform/automations/catalog), toutes deux renvoyant ici. ## Webhooks Clique sur **Ajouter un webhook** et Tale frappe une URL unique ; tout système qui y envoie un POST JSON lance l’exécution, avec le corps de la requête comme entrée de l’exécution. <Warning> Sauvegarde l’URL du webhook au moment où elle s’affiche — le token dans l’URL fait office d’identifiant d’authentification. Quiconque détient l’URL peut lancer le workflow, donc traite-la comme un secret et supprime le webhook pour la révoquer. </Warning> ## Événements Clique sur **Ajouter un déclencheur d'événement** et choisis un type d’événement dans la liste déroulante — des choses qui se produisent dans Tale, comme `task.created`, `conversation.message_received`, `customer.updated` ou `workflow.completed`. Des filtres optionnels resserrent quand le déclencheur se lance, et le payload de l’événement devient l’entrée de l’exécution. Va vers un déclencheur d’événement quand le travail du workflow est de réagir à quelque chose que Tale vient de faire. <Note> Un workflow qui appartient à une [automatisation](/fr/platform/automations/concepts) ne s’exécute que depuis son automatisation — il ne peut pas s’abonner lui-même aux événements. </Note> ## Choisir le bon déclencheur | Utilise … quand | Planification | Webhook | Événement | | -------------------------------------------------- | ------------- | ------- | --------- | | Le travail revient sur une horloge | ✓ | | | | Un système externe signale le travail | | ✓ | | | Quelque chose que Tale a fait est la raison d’agir | | | ✓ | Un workflow peut en porter plus d’un — une planification quotidienne plus un webhook pour des coups d’envoi externes ad hoc forment une paire courante. ## Mettre en pause et supprimer Chaque ligne de déclencheur a une bascule **Actif**. La couper arrête les lancements sans perdre la ligne ni l’historique d’exécution ; la remettre reprend immédiatement. Supprimer la ligne est définitif — pour les webhooks cela tue aussi l’URL, donc tout système qui y envoie encore des POST cesse de fonctionner. ## Où cela s’inscrit Les déclencheurs sont la couche du coup d’envoi ; les étapes derrière eux sont le travail réel. Va sur [Concepts d’automatisation](/fr/platform/automations/concepts) pour le modèle qu’un déclencheur alimente, et sur [Journaux d’exécution](/fr/platform/automations/execution-logs) pour voir ce que chaque exécution lancée a enregistré — y compris quel déclencheur l’a démarrée. # Parcourir et installer des automatisations Source: https://tale.dev/docs/fr/platform/automations/catalog Le catalogue des automatisations (**Automatisations** dans la barre latérale) est l’endroit où les Propriétaires, Admins et Développeurs parcourent chaque automatisation disponible pour l’organisation et décident lesquelles installer. Cette page couvre le catalogue lui-même — le panneau latéral qu’ouvre une carte, l’assistant d’installation, et les actions de réinstallation, désinstallation et mise à jour qui suivent. Ce que fait chaque automatisation livrée vit sur [Automatisations livrées](/fr/platform/automations/builtin) ; le modèle mental des pièces qu’une automatisation empaquette vit sur [Concepts d’automatisation](/fr/platform/automations/concepts). <Frame caption="Le catalogue des automatisations — chaque carte est une automatisation installable ; le bundle installe tous ses membres via un seul assistant."> ![Le catalogue des automatisations sur l’onglet Toutes les automatisations, avec les cartes des trois automatisations d’e-mail et du bundle Résoudre les issues GitHub, chacune avec son icône et sa description.](/images/platform/automations-catalog.webp) </Frame> ## Installées et Toutes les automatisations Le catalogue s’ouvre sur **Installées** — le choix par défaut de la barre d’onglets, et le seul onglet où un bundle se dissout en ses propres cartes membres au lieu d’apparaître une fois comme bundle. Chaque membre porte sur son icône un petit repère nommant son bundle — **Partie de Résoudre les issues GitHub**, par exemple — pour que leur appartenance reste visible même séparés, et chacun garde son propre **Réinstaller**/**Désinstaller** dans son menu **⋯** : un bundle n’a pas d’installation propre à gérer comme un tout (voir [Concepts d’automatisation](/fr/platform/automations/concepts) pour comprendre pourquoi). Passe à **Toutes les automatisations** pour parcourir tout le catalogue à la place — livrées et téléversées, installées ou non : ici, le bundle EST la carte, installée via un seul assistant, et ses membres cachés n’apparaissent jamais seuls. **Installées** sert à gérer ce qui tourne ; **Toutes les automatisations** à trouver du nouveau. ## Installer une automatisation Clique sur une carte et son panneau latéral s’ouvre — le même mode aperçu-au-clic que [Paramètres > Intégrations](/fr/platform/integrations/overview) utilise pour son propre catalogue. Le panneau liste ce que l’installation ajoute : ses pages, workflows, agents, compétences, et les intégrations qu’elle requiert, plus le projet qu’elle cible si elle est scopée à un projet. Clique sur **Installer** et l’assistant s’ouvre. L’assistant ne parcourt que les étapes dont cette automatisation a réellement besoin : une étape **Projet** si elle est scopée à un projet et que tu ne l’as pas ouverte depuis l’intérieur d’un projet ; une étape **Vérifier les changements** si l’installation écraserait des fichiers déjà sur le disque ; une étape **Installer** qui connecte toute intégration requise pas encore connectée ; une étape **Mode de l’agent** pour chaque agent qui peut tourner sur tes propres identifiants plutôt que sur ceux de la plateforme ; et une étape **Terminé**. Le projet que tu choisis à l’étape **Projet** fait double usage : c’est aussi la source dont chaque planification installée par l’automatisation tire sa variable `projectId`, pour qu’un workflow qui lit `{{input.projectId}}` s’exécute contre le bon projet sans que tu aies à la retaper dans l’onglet [Déclencheurs](/fr/platform/automations/triggers). **Terminé** n’annonce « prête » que lorsque l’automatisation l’est vraiment. Si chaque intégration requise est connectée, c’est exactement ce qui s’affiche ; si une variable de planification requise est encore vide — ce qu’aucune étape de l’assistant ne demande, puisque cela dépend du schéma d’entrée propre au workflow —, Terminé la nomme à la place, avec un bouton **Ouvrir les déclencheurs** qui saute directement à la planification concernée (pour un bundle, l’étape Terminé fait la même chose par membre, en nommant ceux qui ont encore besoin d’une variable). Chaque étape de configuration reste rattrapable plus tard, quoi qu’il arrive : une connexion ignorée depuis la checklist **Terminer la configuration** propre à l’automatisation, une variable de planification depuis son onglet [Déclencheurs](/fr/platform/automations/triggers). ## Le contrôle préalable à l’installation Réinstaller ou téléverser à nouveau par-dessus une automatisation dont certains fichiers ont déjà changé déclenche une étape **Vérifier les changements** avant que quoi que ce soit ne soit touché. Pour une automatisation seule, l’étape liste chaque fichier que l’installation écraserait et te demande de confirmer le remplacement de tous par les versions de l’automatisation — pas de sélection fichier par fichier. Installer un **bundle** passe en revue chaque automatisation membre séparément : chacune a sa propre section repliable et sa propre confirmation, pour que tu voies exactement lesquelles des plusieurs automatisations du bundle touchent des fichiers que tu as modifiés. Dans les deux cas, les étapes propres d’un workflow échappent à ce contrôle — voir la section suivante. ## Réinstaller, désinstaller et mettre à jour Chaque carte installée porte un menu **⋯** avec **Réinstaller** et **Désinstaller** ; le menu d’une carte pas encore installée propose **Installer** à la place, plus **Supprimer** pour un envoi privé que tu n’as pas encore installé. **Réinstaller** relance le même contrôle préalable qu’une installation neuve et conserve tes variables d’environnement et tes secrets. **Désinstaller** retire l’automatisation et tout ce qu’elle a installé — ses agents, workflows, pages, et leurs variables d’environnement et secrets — tandis que toute intégration qu’elle utilisait reste connectée pour ce que d’autres en font. Réinstaller ne touche jamais au workflow de l’automatisation : les étapes du workflow sont exemptées de mise à jour, donc tout ce que tu as modifié dans l’éditeur survit à chaque réinstallation et à chaque mise à jour du catalogue. Pour récupérer la dernière version livrée d’un workflow, désinstalle l’automatisation puis réinstalle-la — Tale répète ce rappel sur la confirmation de réinstallation et sur l’onglet Configuration propre à l’automatisation. **Mettre à jour les automatisations livrées**, dans le même menu **Ajouter une automatisation** que **Téléverser un package**, est une action différente des deux précédentes : elle resynchronise en un seul passage toutes les automatisations livrées de l’organisation avec le catalogue livré — y compris celles que tu as modifiées — plutôt qu’une carte à la fois. Elle porte la même exemption de workflow et conserve les secrets ; la version précédente de tout ce qu’elle change atterrit dans l’historique de cette automatisation. ## Téléverser une automatisation privée **Téléverser un package**, dans le même menu, ajoute une automatisation que le catalogue ne livre pas — dépose un `.zip`, ou sélectionne un dossier contenant un `automation.json` à sa racine ; le nom du dossier ou du fichier devient le slug de l’automatisation. Téléverser ne fait que l’ajouter au catalogue privé de l’organisation ; installe-la ensuite comme n’importe quelle autre carte. Téléverser à nouveau par-dessus un slug qui existe déjà te demande de confirmer le remplacement avant d’écraser le package existant. ## Où cela s’inscrit Le catalogue est la porte d’entrée vers chaque automatisation que l’organisation peut faire tourner : le panneau latéral prévisualise ce que l’installation ajoute, l’assistant connecte ce dont elle a besoin, et réinstaller, désinstaller et mettre à jour la gardent à jour sans toucher à un workflow que tu es en train de modifier. [Automatisations livrées](/fr/platform/automations/builtin) est la lecture suivante pour ce que fait chaque automatisation livrée et le bundle Résoudre les issues GitHub ; [Concepts d’automatisation](/fr/platform/automations/concepts) est le modèle mental si tu ne l’as pas encore lu. # Approbations dans les workflows Source: https://tale.dev/docs/fr/platform/automations/approvals-in-workflows Les workflows s’exécutent sans toi, mais ils ne changent et ne démarrent qu’avec toi. Trois portes humaines entourent chaque workflow : les modifications de l’éditeur IA sur une définition ne s’appliquent qu’après ton approbation, un agent qui veut exécuter un workflow a d’abord besoin de ton accord, et une exécution qui rencontre une question se met en pause jusqu’à ce que quelqu’un réponde. Cette page couvre les trois portes ; l’histoire à l’échelle de l’org de ce qu’est une carte d’approbation vit sur [Concepts d’approbation](/fr/platform/approvals/concepts). <Frame caption="L’éditeur IA à côté du canevas — ses modifications arrivent comme cartes d’approbation, jamais comme changements silencieux de la définition."> ![L’éditeur de workflow avec un graphe d’étapes sur le canevas et le panneau de l’éditeur IA ouvert à droite, où les modifications de workflow proposées apparaissent pour approbation.](/images/platform/automation-editor-canvas.webp) </Frame> ## Approuver les modifications d’une définition Demande à l’**Éditeur IA** de construire ou de retravailler un workflow et sa proposition arrive comme une carte dans le panneau — une carte **Créer le workflow** avec le nombre d’étapes pour une nouvelle définition, ou une carte de mise à jour badgée selon la portée : **Mettre à jour l'étape** pour un correctif d’une seule étape, **Mettre à jour {count} étapes** pour plusieurs, **Mettre à jour le workflow** pour un enregistrement complet. Approuve et le changement est appliqué et versionné comme n’importe quel enregistrement manuel ; **Annuler** l’écarte. Rien ne touche la définition tant que la carte est en attente. ## Approuver une exécution Un agent en chat doté des outils de workflow peut demander à démarrer un workflow. La demande arrive comme une carte nommant le workflow — déplie **Afficher les paramètres** pour inspecter l’entrée exacte avec laquelle il s’exécutera — et tient jusqu’à ce que tu cliques sur **Exécuter le workflow** ou **Annuler**. Après approbation, la même carte suit l’exécution en direct : l’étape en cours, le temps écoulé et l’issue, avec **Arrêter** pour annuler en vol et **Voir les détails de l'exécution** pour sauter au journal de l’exécution. <Note> Le composeur du chat est bloqué tant qu’une demande est en attente — **Réponds à la demande en attente ci-dessus pour continuer**. Décide la carte avant d’envoyer le message suivant. </Note> ## Répondre à une exécution en pause Une exécution qui a besoin d’une réponse humaine se met en pause avec le statut **En attente de saisie** dans la [liste des exécutions](/fr/platform/automations/execution-logs). La question arrive comme une carte-formulaire — remplis-la et clique sur **Soumettre la réponse**, ou clique sur **Répondre différemment** pour répliquer en texte libre. L’exécution reprend avec ta réponse comme entrée de l’étape, et le journal enregistre qui a répondu et quoi. ## Ce que chaque décision laisse derrière elle Chaque porte se résout vers les mêmes états — **En attente**, **Exécution**, **Terminé** ou **Rejeté** — visibles sur la carte elle-même, et la décision atterrit dans le [journal d’audit](/fr/platform/admin/governance/audit-logs) avec l’acteur et l’horodatage. Une carte résolue ne peut pas être rouverte ; pour retenter une exécution rejetée, redemande et décide la carte neuve. ## Où cela s’inscrit Ces portes sont la face côté workflow d’un motif qui traverse tout le produit : un agent propose, un humain dispose. [Concepts d’approbation](/fr/platform/approvals/concepts) nomme chaque type de carte au-delà des workflows — écritures de documents, écritures de connaissances, appels d’intégration — et [Configurer les approbations](/fr/platform/approvals/configure) montre où les exigences sont déclarées. # L’éditeur de workflow Source: https://tale.dev/docs/fr/platform/automations/editor Cette page est le manuel d’exploitation du workflow qui vit dans une automatisation — la surface derrière l’onglet **Éditeur**. Le modèle mental — ce qu’une automatisation empaquette et ce qu’est une définition, un déclencheur et une exécution — vit sur [Concepts d’automatisation](/fr/platform/automations/concepts). Cette page est la moitié pratique : où vit le workflow, comment tu le lances depuis l’UI, comment tu le mets en pause sans le supprimer, comment tu édites et comment l’historique versionné fonctionne. Les rôles Éditeur et Développeur lisent ceci quand ils travaillent avec un workflow au quotidien. ## Où vivent les workflows Les workflows n’ont pas d’onglet à eux dans la barre latérale. Un workflow appartient à l’automatisation qu’il fait tourner — ouvre l’automatisation et son onglet **Éditeur** est le workflow ; tu gères tout ce qui suit depuis là. Un lien direct vers un workflow continue de fonctionner quand quelqu’un le partage ; les favoris et les liens des cartes d’approbation et des vues d’exécution atterrissent sur le workflow lui-même. Chaque surface que cette page couvre (l’éditeur, l’onglet exécutions, l’historique de versions) pend à un workflow unique que tu as ouvert. ## Lancer un workflow Trois chemins déclenchent un workflow. L’onglet **Déclencheurs** du workflow attache les chemins de production : les **Planifications** se déclenchent sur un cron, les **Webhooks** acceptent un POST externe et les **Événements** s’abonnent à des signaux internes comme `task.created`. La [référence des déclencheurs](/fr/platform/automations/triggers) couvre chacun en profondeur. **Tester le workflow** dans la barre d’outils de l’éditeur ouvre le panneau de test et lance une exécution ponctuelle. Colle le JSON d’entrée que l’exécution doit recevoir, clique sur **Exécuter**, et l’exécution apparaît dans l’onglet Exécutions avec son ID. Sers-toi du panneau de test quand tu itères sur un workflow et veux voir le journal d’exécution complet sans câbler de déclencheur d’abord. Pendant que l’exécution tourne, le canevas la reflète en direct : chaque étape porte un badge de statut — un spinner pendant l’exécution, une coche en cas de succès, une alerte en cas d’échec, une icône pause en attente de saisie — et une bannière au-dessus du canevas nomme l’exécution affichée. Clique sur un badge pour inspecter la durée de l’étape, son erreur et un aperçu de sa sortie. L’exécution affichée tient dans le paramètre d’URL `execution` et survit donc à un rechargement ; ferme la bannière pour effacer les badges. Le panneau de test reflète le même flux sous forme de liste d’étapes : chaque étape exécutée apparaît avec son statut en direct, les étapes répétées ou en boucle portent un compteur de tentatives, et une étape en échec affiche son message d’erreur en ligne — clique sur le nom de l’étape pour sauter directement à ses réglages. Quand une exécution échoue avant qu’aucune étape n’ait tourné — jamais démarrée, délai dépassé ou annulée —, le panneau nomme cette raison à la place. Les exécutions de test valident aussi l’entrée côté serveur contre le schéma de l’étape de départ : un champ manquant ou mal typé est rejeté avec un message précis avant même que l’exécution ne soit créée. Le bouton **Déboguer** dans le même panneau lance l’exécution en mode pas à pas. Le moteur s’arrête avant chaque étape : l’étape en pause porte un badge de débogage sur le canevas, et le panneau montre quelle étape vient ensuite, avec les variables de l’exécution et la sortie de chaque étape terminée — tu vérifies donc ce qu’une étape va recevoir avant de la laisser tourner. **Pas à pas** exécute l’étape en pause et s’arrête de nouveau avant la suivante, **Continuer** déroule le reste du workflow sans autre pause, **Arrêter** annule l’exécution. Les exécutions de débogage apparaissent dans l’onglet Exécutions avec un badge _En pause (débogage)_ tant qu’elles sont en pause et `debug` comme source de déclenchement. Le bouton **Exécution à blanc** dans le même panneau simule une exécution sans effets de bord — le workflow valide l’entrée, parcourt le graphe d’étapes et signale erreurs et avertissements sans appeler le moindre agent, la moindre API ni le moindre serveur de mail. Sers-toi de l’exécution à blanc quand le workflow n’est pas encore sûr à exécuter de bout en bout. ## Mettre en pause et désactiver Mettre un workflow en pause sans le supprimer passe par les déclencheurs — chaque ligne de déclencheur porte un interrupteur **Actif**. Bascule chaque déclencheur sur off et le workflow cesse de se déclencher ; remets-les sur on pour reprendre. Le workflow lui-même reste en place et son historique reste intact. Supprimer un workflow est permanent. Tale demande confirmation avant la suppression ; les exécutions et l’historique de versions partent avec le workflow. ## Éditer Ouvre le workflow et l’éditeur affiche le graphe d’étapes sur un canevas — c’est la vue **Graphe**, l’une des deux façons de lire la même définition. Bascule sur **Spécification** et le même workflow se lit comme une description en langage naturel que tu peux éditer directement ; régénérer depuis l’une ou l’autre vue garde les deux synchronisées, et une bannière avertit quand elles ont divergé. Clique sur une étape du graphe pour ouvrir son panneau **Éditeur d'étapes** à droite ; le panneau porte le nom de l’étape, son type, sa configuration et les transitions vers les étapes suivantes en cas de succès et d’échec. La barre d’outils du canevas porte les contrôles de zoom, **Tester le workflow** et le bouton **Éditeur IA** — un chat qui édite le workflow à ta place, le même [Assistant d’automatisation](/fr/platform/automations/assistant) embarqué ici. Ajouter des étapes directement sur le canevas n’est pas encore possible ; les nouvelles étapes viennent de l’éditeur IA ou de la spécification. La bannière **Ce workflow est actif — les modifications enregistrées s’appliquent aux nouvelles exécutions.** au-dessus du canevas dit exactement cela : les modifications d’un workflow déclenché prennent effet à la prochaine exécution. Désactive d’abord ses déclencheurs quand les modifications ne sont pas prêtes. ## Versionnage et historique Chaque sauvegarde fige une nouvelle version du workflow. **Historique** dans la navigation du workflow liste les versions, plus récente en tête, chacune avec un horodatage et le membre qui a sauvegardé. En ouvrir une montre un diff **Comparer les modifications** contre la définition actuelle ; clique sur **Restaurer** pour revenir à cette capture. Restaurer crée une nouvelle version au sommet de l’historique — l’état restauré devient le nouvel état courant, et la version que tu as remplacée reste dans la liste. L’historique est par workflow, pas par étape. Restaurer rétablit toute la définition ; les restaurations partielles vivent dans l’éditeur (copie la config de l’étape depuis le diff et colle-la dans la version actuelle). Réinstaller ou mettre à jour l’automatisation à laquelle ce workflow appartient ne touche jamais à ces étapes — un workflow est exempté de cet écrasement, précisément pour que tes modifications survivent à une mise à jour du catalogue. Désinstalle l’automatisation et réinstalle-la pour récupérer à la place son dernier workflow livré. ## Où ça s’inscrit Cette page est le manuel d’exploitation ; [Concepts d’automatisation](/fr/platform/automations/concepts) est le modèle mental. Les voisins naturels sont les [déclencheurs](/fr/platform/automations/triggers) (le coup d’envoi), les [journaux d’exécution](/fr/platform/automations/execution-logs) (le détail par exécution) et les [approbations dans les workflows](/fr/platform/automations/approvals-in-workflows) (la barrière humaine entre les étapes). Sers-toi de cette page quand tu travailles sur un workflow qui existe déjà ; sers-toi des concepts quand tu construis le premier. # Plateforme Source: https://tale.dev/docs/fr/platform Plateforme est la référence produit canonique : chaque fonctionnalité visible par l’utilisateur dans Tale, identique pour Cloud et auto-hébergé. Les pages ici décrivent l’UI qu’on clique, le concept derrière l’UI, et les arbitrages entre fonctionnalités qui se ressemblent. La section est organisée par domaine, puis par fonctionnalité au sein d’un domaine. La plupart des lecteurs ne la lisent pas de bout en bout — ils atterrissent ici depuis une recherche ou un lien de tutoriel, et la page sur laquelle ils tombent doit répondre à la question qu’ils ont apportée. ## Domaines de fonctionnalités <CardGroup cols="2"> <Card title="Chat" icon="message-circle" href="/fr/platform/chat/overview"> Le point d’entrée quotidien — conversations, agents dans le chat, pièces jointes, mode arène, mode vocal, le volet canevas, partage. </Card> <Card title="Projets" icon="folder-open" href="/fr/platform/projects/overview"> Espaces partagés qui regroupent fichiers, instructions, conversations et agents liés au projet. </Card> <Card title="Agents" icon="bot" href="/fr/platform/agents/concepts"> Instructions, connaissances, outils, modèle — plus compétences, workers, versionnage et déclencheurs webhook. </Card> <Card title="Automatisations" icon="layout-grid" href="/fr/platform/automations/concepts"> Des paquets installables qui regroupent intégrations, agents, compétences et un workflow — le catalogue, l’assistant d’installation, l’éditeur et les déclencheurs derrière chaque automatisation, et l’historique des runs qu’elle laisse. </Card> <Card title="Connaissances" icon="library" href="/fr/platform/knowledge/overview"> Documents, clients, produits, fournisseurs, sites web — le modèle de données structurées que les agents citent. </Card> <Card title="Approbations" icon="check-check" href="/fr/platform/approvals/concepts"> Cartes inline, points dans les workflows et le pool d’approbateurs qui garde les humains dans la boucle. </Card> <Card title="Bibliothèque de prompts" icon="list-plus" href="/fr/platform/workspace/prompt-library"> Prompts enregistrés avec visibilité personnelle, d’équipe et globale, plus l’historique des versions. </Card> <Card title="Modèles" icon="cpu" href="/fr/platform/models"> Le catalogue de modèles derrière chaque sélecteur — étiquettes de capacité, valeurs par défaut et la liste livrée. </Card> <Card title="Intégrations" icon="plug" href="/fr/platform/integrations/overview"> Appariements SaaS tiers et serveurs MCP. </Card> </CardGroup> ## Prépare ta première journée Quatre entrées indexées par rôle cartographient les mêmes fonctionnalités du côté du lecteur — ce qu’un Membre, un Éditeur, un Développeur ou l’Administration touche réellement le premier jour. <CardGroup cols="2"> <Card title="Membre" icon="user" href="/fr/platform/member/overview"> Chat, connaissances, préférences personnelles — la surface que la plupart des gens utilisent dans la plupart des orgs. </Card> <Card title="Éditeur" icon="pencil-ruler" href="/fr/platform/editor/overview"> La surface de construction — agents, curation des connaissances, automatisations, projets. </Card> <Card title="Développeur" icon="terminal" href="/fr/platform/developer/overview"> Clés API, outils personnalisés, webhooks, serveurs MCP — brancher Tale à du code externe. </Card> <Card title="Administration" icon="shield" href="/fr/platform/admin/overview"> Paramètres de l’organisation, fournisseurs, branding, intégrations et le sous-arbre gouvernance. </Card> </CardGroup> ## Où cela s’inscrit Plateforme est le puits gravitationnel — Cloud et auto-hébergé pointent tous deux ici pour la documentation des fonctionnalités, et chaque tutoriel cite des pages d’ici pour les concepts sous-jacents. La page à mettre en favori dès le premier jour est [Agents → concepts](/fr/platform/agents/concepts) — presque toutes les autres pages produit supposent le modèle mental à quatre boutons que cette page construit. # Membre Source: https://tale.dev/docs/fr/platform/member/overview Membre est le rôle par défaut que portent la plupart des personnes dans la plupart des orgs. C’est la surface utilisateur final de Tale — chatter avec des agents, parcourir la base de connaissances, répondre au courriel client dans la Boîte de réception d’une automatisation installée, agir sur les approbations que d’autres ont routées vers toi, et laisser des retours sur les réponses. Les Membres ne construisent pas d’agents, ne configurent pas de fournisseurs, n’installent pas d’automatisations. Ils utilisent le produit que les Éditeurs et Développeurs ont bâti pour eux. Cette vue d’ensemble nomme ce qu’un Membre peut faire et pointe vers les pages par fonctionnalité. Les Membres atterrissent typiquement d’abord sur Chat ; le reste de cette page est ce qu’il faut lire quand chat seul ne suffit pas — quand tu veux savoir d’où vient une citation, ce qu’est une carte d’approbation, ou ce qu’empaquette un projet. ## Ce que couvre Membre La surface Membre est volontairement étroite. Les quatre seaux sont : - **Chat** — choisir un agent (ou aucun), envoyer un message, lire la réponse. Le composeur expose la bibliothèque de prompts, les pièces jointes, le mode vocal, le mode arène pour la comparaison côte à côte, et le panneau Canevas quand une réponse produit plus que le chat peut tenir en ligne. - **Connaissance** — parcourir les documents, clients, produits, fournisseurs, sites web que l’org a chargés. Lecture seule pour les Membres ; la curation arrive du côté Éditeur. - **Boîte de réception** — répondre dans l’onglet **Boîte de réception** qu’ajoute une automatisation d’e-mail installée. Les Membres répondent quand un agent leur rend une conversation ; installer l’automatisation elle-même est une action d’admin. - **Approbations** — lire les cartes d’approbation routées vers toi. Clique sur Approuver, Rejeter, ou Demander des changements ; laisse un commentaire si la règle le demande. Les réglages de configuration de l’org — Fournisseurs, Intégrations, Agents, Gouvernance — sont cachés pour les Membres ; la surface travail est l’essentiel de ce qui reste. L’exception est un petit groupe de réglages personnels que porte chaque rôle : Compte, Personnalisation et [Variables d’environnement et secrets](/fr/platform/member/environment), les clés et variables injectées dans les sandboxes que tu fais tourner. ## Pages dans cette section Cette section est courte — la surface Membre est l’intersection des pages que les Éditeurs construisent et que tout le monde utilise. La lecture plus profonde vit dans les zones par fonctionnalité. <CardGroup cols="2"> <Card title="Chat" icon="message-circle" href="/fr/platform/chat/overview"> Le point d’entrée quotidien — composer, agents, pièces jointes, citations. </Card> <Card title="Connaissance" icon="library" href="/fr/platform/knowledge/overview"> La fenêtre lecture seule sur ce que l’org a chargé. </Card> <Card title="Automatisations livrées" icon="inbox" href="/fr/platform/automations/builtin"> Les automatisations d’e-mail qui ajoutent un onglet Boîte de réception — et ce que fait chacune. </Card> <Card title="Approbations" icon="check-check" href="/fr/platform/approvals/concepts"> Ce qu’est une carte d’approbation et ce que fait chaque bouton. </Card> </CardGroup> ## Où cela s’inscrit Membre est le rôle qui consomme ce que l’Éditeur construit et que l’Administrateur gouverne. La première lecture naturelle est [Chat](/fr/platform/chat/overview) — c’est là que chaque Membre passe le plus de temps, et la plupart des autres surfaces Membre se déploient depuis un chat qui voulait faire plus. # Préférences Source: https://tale.dev/docs/fr/platform/member/preferences Les préférences sont les molettes qui t’appartiennent plutôt qu’à l’org. Ton nom est ce que voient agents et coéquipiers dans les chats et les approbations. Ta langue et ton thème te suivent entre les appareils. Tes instructions personnalisées et tes mémoires façonnent la manière dont les agents te répondent spécifiquement — séparément de tout ce que l’Administrateur ou l’Éditeur a posé au niveau de l’org. Cette page cartographie où vit chaque levier et ce qu’il change. La forme est volontairement à deux couches : le menu de profil (partout, à un clic de l’avatar) porte les bascules rapides ; **Paramètres > Compte** et **Paramètres > Personnalisation** portent les champs de compte plus profonds. Tout ici t’appartient — rien ne fuite vers d’autres membres ou d’autres orgs. ## Le menu de profil Clique ton avatar en haut à droite. Le menu déroulant s’ouvre avec ton nom, ton e-mail et la version de build actuelle. Sous l’en-tête se trouvent quatre contrôles rapides que voit chaque membre quelle que soit sa rôle : le sélecteur de **thème** (Système / Clair / Sombre), le sous-menu de **langue** (English, Deutsch, Français), la ligne **Installer l'app** quand le navigateur peut installer Tale en tant que PWA, et **Se déconnecter**. Le thème et la langue prennent effet immédiatement et persistent par appareil. Le menu porte aussi un sélecteur d’organisation quand tu appartiens à plus d’une org et un filtre d’équipe quand ton org actuelle a des équipes. Ce ne sont pas des préférences — ils changent ce que Tale t’affiche, pas la manière dont Tale se comporte. Sous le filtre d’équipe, **Paramètres utilisateur** ouvre **Paramètres > Compte**, la page couverte ensuite. ## Compte — nom, e-mail, mot de passe, double authentification Ouvre **Paramètres > Compte**. Trois sections siègent sur la page : **Profil**, **Sécurité** et **Authentification à deux facteurs**. La section Profil affiche d’abord ton **e-mail**, puis ton **nom** — l’e-mail suggère le nom que Tale propose, que tu peux modifier librement. Le nom s’édite en ligne ; la modification s’enregistre et se propage dans chaque chat et chaque approbation au prochain rendu. L’e-mail est en lecture seule — c’est avec lui que tu t’es connecté, et un changement passe par le support. Il n’y a pas de champ avatar sur la page ; Tale dérive un avatar à partir des initiales de ton nom. La section Sécurité tient un seul bouton : **Changer le mot de passe** si tu t’es inscrit avec e-mail et mot de passe, **Définir le mot de passe** si ton compte est fédéré via SSO et que tu veux ajouter un mot de passe comme repli. Les deux flux imposent la politique de mot de passe de l’org et affichent les règles en direct pendant que tu tapes, et un mot de passe actuel erroné est signalé directement sur le champ plutôt que comme une erreur passagère. Changer ton mot de passe te déconnecte de tous les appareils — le dialogue t’avertit avant que tu confirmes, et tu te reconnectes ensuite avec le nouveau mot de passe. La section Deux-facteurs apparie le compte à une app TOTP ou à une clé matérielle et affiche les codes de secours une fois à l’enrôlement. ## Personnalisation — instructions, mémoires, sortie vocale Ouvre **Paramètres > Personnalisation**. La page conditionne chaque fonctionnalité avec une bascule on/off qui suit la valeur par défaut de l’org jusqu’à ce que tu la remplaces. <Frame caption="Paramètres > Personnalisation — les bascules par fonctionnalité au-dessus du champ d’instructions personnalisées, de la liste des mémoires et du sélecteur de sortie vocale."> ![La page de paramètres Personnalisation, montrant les bascules on/off pour les instructions personnalisées, les mémoires et la sortie vocale, avec le champ texte d’instructions personnalisées et la liste des mémoires enregistrées en dessous.](/images/platform/settings-preferences.webp) </Frame> **Instructions personnalisées** est un champ texte libre — jusqu’à 4 000 caractères — que chaque agent reçoit comme contexte additionnel spécifiquement pour tes conversations. Utilise-le pour ce que tu dirais sinon en tête de chaque chat : ton rôle, ton style de réponse préféré, les projets sur lesquels tu travailles, les contraintes que l’agent doit respecter. La valeur par défaut de l’org décide si la fonctionnalité est active pour les nouveaux membres ; ta bascule la remplace pour ton propre compte. **Mémoires** sont de courts faits que l’agent enregistre sur toi entre les chats — un sujet sur lequel tu as posé une question, une préférence que tu as exprimée, un contexte que tu ne voudrais pas répéter. Les mémoires enregistrées apparaissent dans une liste avec un bouton supprimer sur chaque ligne ; les mémoires en attente surgissent dans leur propre section avec les contrôles **Approuver** et **Écarter** pour que rien ne se pose dans ton dossier sans que tu le voies. Bascule la fonctionnalité sur off et les mémoires existantes cessent d’être utilisées jusqu’à ce que tu la rallumes. **Sortie vocale** choisit la voix qu’un agent utilise quand il parle en mode vocal. Le réglage ne s’applique que quand l’org a configuré un fournisseur de voix ; sinon la section explique le manque et pointe vers l’Administrateur. ## Se déconnecter La ligne **Se déconnecter** en bas du menu de profil confirme via une boîte de dialogue avant de purger la session. Après confirmation, Tale fait un rechargement complet vers la page de connexion pour qu’aucun état périmé ne traîne dans l’onglet. La déconnexion est par appareil — te déconnecter sur ton laptop ne te déconnecte pas sur ton téléphone, et réciproquement. ## Où cela s’inscrit Les préférences sont la ligne entre toi et le reste de l’org. L’Administrateur de l’org pose les valeurs par défaut — y compris si la personnalisation est active pour les nouveaux membres, quelle est la politique de mot de passe, quels modèles sont autorisés — et tes préférences remplacent les valeurs par défaut là où Tale le permet. Une page personnelle se tient à l’écart de cet ensemble : [Variables d’environnement et secrets](/fr/platform/member/environment) porte des variables et des identifiants cantonnés à toi au sein d’une seule organisation plutôt qu’ils ne te suivent d’une org à l’autre — l’endroit où garder la clé de fournisseur qu’utilise un agent BYO. La lecture suivante à mettre en file est [Vue d’ensemble Membre](/fr/platform/member/overview) pour la carte du reste de la surface Membre, ou [Installer en tant qu’app](/fr/platform/member/install-as-app) si tu veux que Tale vive dans ton dock plutôt que dans tes onglets de navigateur. # Variables d’environnement et secrets Source: https://tale.dev/docs/fr/platform/member/environment Variables d’environnement et secrets est ton magasin personnel de variables que Tale injecte dans chaque sandbox d’agent que tu lances dans cette organisation. Quand un agent externe démarre sa sandbox, chaque entrée que tu as enregistrée ici est posée dans l’environnement du conteneur avant que l’agent tourne, pour qu’une commande lancée par l’agent — ou l’agent lui-même — puisse la lire. L’usage phare, ce sont les identifiants : un [agent externe en mode BYO](/fr/platform/agents/external-agent) s’authentifie avec la clé API ou le jeton que tu gardes ici plutôt qu’avec la passerelle de la plateforme. C’est une page de niveau membre que chaque rôle peut atteindre, et les entrées sont cantonnées à toi et à l’organisation actuelle, donc elles ne fuient jamais vers tes coéquipiers et ne te suivent jamais dans une autre org. Cette page couvre les deux types d’entrée, comment les secrets sont protégés, les règles qu’un nom et une valeur doivent respecter, et où les valeurs finissent. <Frame caption="Paramètres > Environnement — les entrées enregistrées, chacune avec l’interrupteur Secret qui décide si sa valeur peut être relue."> ![La page de paramètres Environnement listant trois entrées enregistrées — ANALYTICS_ORG et CRM_BASE_URL avec leurs valeurs en clair, et CRM_API_TOKEN masquée en points avec sa case Secret cochée — au-dessus de l’action Ajouter une variable.](/images/platform/settings-environment.webp) </Frame> ## Variables et secrets Ouvre **Paramètres > Environnement**. **Ajouter une variable** ouvre une boîte de dialogue pour une nouvelle entrée, avec la liste de ce que tu as enregistré en dessous. Chaque entrée est un **Nom** et une **Valeur**, plus une bascule **Secret** qui décide comment la valeur est stockée et affichée. Une variable simple est stockée telle quelle et réaffichée en entier dans la liste — utilise-la pour la configuration non sensible que l’agent attend, un nom de région ou un endpoint. Un **secret** est chiffré dès l’instant où tu l’enregistres et devient en écriture seule à partir de là : la liste montre `••••••••` à la place de la valeur, et il n’y a aucun moyen de la relire. Active la bascule pour tout ce qui est sensible — une clé API, un jeton OAuth, un mot de passe. Le compromis, c’est que tu ne peux pas revoir la valeur d’un secret plus tard, donc si tu n’es pas sûr qu’elle soit bonne, supprime-le et ajoute-le à nouveau plutôt que de chercher un bouton d’affichage qui n’existe pas. Chaque ligne porte le nom, la valeur ou son masque, et la date de dernière mise à jour. L’icône corbeille demande confirmation avant de retirer l’entrée, car en supprimer une la sort de chacune de tes sandboxes au prochain lancement. ## Noms, valeurs et limites Un **nom** doit commencer par une lettre ou un tiret bas et ne contenir que des lettres, des chiffres et des tirets bas — la forme d’une variable d’environnement ordinaire, `MY_API_KEY` plutôt que `my-api.key`. Les noms sont plafonnés à 128 caractères et les valeurs à 8 192, ce qui laisse la place pour un long jeton ou une clé multiligne mais pas pour un fichier. Tu peux garder jusqu’à 100 entrées. Tale rogne les espaces au début et à la fin d’une valeur quand tu l’enregistres, parce qu’un saut de ligne égaré venu d’un copier-coller est la cause la plus fréquente d’un jeton qui échoue silencieusement. Il ne rogne pas les espaces ni les sauts de ligne _à l’intérieur_ de la valeur, mais il te prévient quand il en trouve : un identifiant n’en a normalement aucun, donc un blanc intérieur signifie d’ordinaire un jeton qui s’est replié sur plusieurs lignes dans ton terminal au moment du collage. L’avertissement ne bloque pas l’enregistrement — un secret réellement multiligne comme une clé privée PEM garde ses sauts de ligne — donc lis-le et décide. ## Comment les valeurs atteignent la sandbox Un secret ne voyage jamais en clair, sauf vers ta propre sandbox. Au repos il est chiffré dans le backend de Tale sous une clé que la plateforme détient, et la requête de liste ne renvoie que le masque, jamais le texte en clair. Quand un tour démarre, la plateforme déchiffre tes secrets et les pose, aux côtés de tes variables simples, dans l’environnement de ta sandbox pour ce lancement. Chaque fois qu’un secret est injecté pour un tour, cet accès est consigné dans le journal d’audit. Cette dernière étape est la frontière à comprendre : les valeurs atterrissent à l’intérieur de ton conteneur sandbox, donc c’est l’isolement de la sandbox — et non le magasin de secrets — qui se tient entre tes identifiants et tout ce qui tourne là. C’est le même fonctionnement que le jeton GitHub dans la sandbox, et c’est pour cela que ces entrées sont cantonnées à toi seul plutôt que partagées avec l’org. C’est aussi ce qui rend possible un [agent BYO](/fr/platform/agents/external-agent) tout court : l’identifiant fournisseur qu’il utilise pour atteindre son modèle est l’un de ces secrets. ## Où cela s’inscrit Variables d’environnement et secrets est l’unique page de niveau membre qui atteint la sandbox plutôt que le chat — c’est par elle que tes propres clés et ta configuration parviennent aux agents que tu lances, sans qu’un Éditeur ou un Admin ne les pose à ta place. L’entrée que tu ajouteras le plus souvent est l’identifiant fournisseur d’un [agent externe en mode BYO](/fr/platform/agents/external-agent) ; lis cette page en parallèle de celle-là pour voir les deux moitiés — où l’identifiant est stocké et comment on dit à un agent de l’utiliser au lieu de la passerelle de la plateforme. Pour le reste de tes réglages personnels — nom d’affichage, mot de passe, instructions personnalisées — vois [Préférences](/fr/platform/member/preferences). # Installer en tant qu'app Source: https://tale.dev/docs/fr/platform/member/install-as-app Tale est livré comme Progressive Web App. L'installer pose une icône dans ton dock ou sur ton écran d'accueil, lance Tale dans sa propre fenêtre sans l'habillage du navigateur, et garde la même session que tu avais dans le navigateur. Il n'y a pas de build natif séparé à télécharger et pas d'extension à installer — la même URL avec laquelle tu te connectes est la même app, dans une coque autonome. Cette page couvre les trois endroits où tu déclenches l'installation : la ligne **Installer l'app** dans ton menu de profil sur les navigateurs Chromium, l'étape de la feuille de partage sur iOS Safari, et la bannière d'installation qu'Android Chrome affiche de lui-même. Une fois installé, Tale se comporte de manière identique ; l'installation ne change que l'habillage autour. ## Le raccourci du menu de profil Sur Chrome, Edge, Brave, Arc et les autres navigateurs Chromium, le menu déroulant de profil de Tale porte une ligne **Installer l'app** quand le navigateur est prêt à installer. Ouvre le menu depuis ton avatar en haut à droite, fais défiler après le sélecteur de thème et le sélecteur de langue, et clique **Installer l'app**. Le navigateur ouvre sa confirmation d'installation native ; accepte-la, et Tale atterrit dans ton dock (macOS), ta barre des tâches (Windows) ou ta liste d'apps (ChromeOS) en une seconde ou deux. La ligne n'est là que quand le navigateur a tiré son événement `beforeinstallprompt` et que l'app n'est pas déjà installée. Les navigateurs qui ne tirent pas cet événement — Firefox, Safari, tout en fenêtre privée — n'affichent pas la ligne, donc le menu reste plus court d'un élément plutôt que de promettre ce qu'il ne peut pas livrer. ## iOS et iPadOS iOS Safari ne tire pas `beforeinstallprompt`, donc la ligne **Installer l'app** n'apparaît pas dans le menu. Le chemin d'installation vit dans la feuille de partage de Safari à la place. Ouvre Tale dans Safari, tape l'icône de partage dans la barre d'outils, fais défiler jusqu'à **Sur l'écran d'accueil**, et confirme. Tale apparaît sur ton écran d'accueil avec la même icône que la favicon du navigateur. Tape dessus, et Tale s'ouvre dans sa propre fenêtre — pas de barre d'adresse Safari, pas de barre d'onglets, pas de bouton retour au-delà de ce que Tale lui-même expose. Les notifications fonctionnent de la même manière que dans l'onglet du navigateur ; l'installation est la seule différence. Les autres navigateurs iOS — Chrome, Edge, Firefox sur iOS — sont Safari sous le capot. Ils n'ont pas leur propre entrée Sur-l'écran-d'accueil. Le chemin Safari est le seul chemin d'installation iOS qui produit une vraie app autonome. ## Android Android Chrome gère l'installation à deux endroits. Le premier est la même ligne **Installer l'app** dans le menu de profil de Tale, identique au flux desktop. Le second est la bannière d'installation propre à Chrome — une barre d'une ligne qui glisse depuis le bas de la page sur les sites qu'il considère installables. Tape **Installer** sur la bannière, confirme dans la feuille système, et Tale atterrit sur ton écran d'accueil. Si tu as écarté la bannière une fois, elle ne revient généralement pas avant un moment. Le raccourci du menu de profil continue à fonctionner que la bannière ait été affichée ou non. Les autres navigateurs Android — Firefox, Samsung Internet, Brave — ont chacun leur propre chemin d'installation dans le menu du navigateur, généralement étiqueté **Installer l'app** ou **Sur l'écran d'accueil**. ## Après l'installation Tale tournant dans une fenêtre PWA est le même Tale tournant dans un onglet de navigateur. La session, les chats, la base de connaissances, les agents — tout cela est la même surface. Les différences sont cosmétiques et petites : pas d'habillage navigateur autour de la fenêtre de l'app, une icône dans ton lanceur, et sur la plupart des plateformes la fenêtre se rappelle de sa taille et de sa position entre les lancements. La désinstallation suit la convention de la plateforme. Sur macOS, glisse l'icône hors du dock ; sur Windows, clic droit et désinstaller ; sur iOS et Android, appui long sur l'icône et retirer. La désinstallation efface la coque PWA mais pas la session — reconnecte-toi via le navigateur, et tes données sont là où tu les as laissées. ## Quand y recourir L'installation vaut le coup dès que tu te retrouves à ouvrir Tale chaque jour et que tu veux qu'il se sente comme une de tes apps plutôt que comme un de tes onglets. C'est aussi le bon mouvement quand tu veux la fenêtre de chat épinglée sur un bureau virtuel ou une fente Stage Manager que les onglets de navigateur ne respecteraient pas. Saute l'installation si tu te connectes depuis beaucoup de machines et préfères l'onglet du navigateur — Tale marche pareil dans les deux cas. La lecture voisine est [Vue d'ensemble Membre](/fr/platform/member/overview) — c'est la carte de ce que couvre le reste de la surface Membre une fois Tale posé dans ton dock. # Projets Source: https://tale.dev/docs/fr/platform/projects/overview Un projet est un espace de travail partagé qui regroupe tout ce dont un travail a besoin — les chats, les fichiers de référence, les instructions, le tableau des tâches et les discussions — pour que le contexte suive le travail au lieu d’être recollé dans chaque chat. Là où un chat isolé répond à une question, un projet est l’endroit où une équipe fait avancer un client, un lancement ou une enquête au long cours. <Frame caption="Le tableau des tâches d’un projet — l’un des huit onglets que porte chaque projet."> ![Un tableau kanban de tâches dans le projet Website relaunch, avec sept cartes de tâches réparties sur les colonnes Backlog, À faire, En cours, En revue, Terminé et Annulé.](/images/platform/projects-task-board.webp) </Frame> ## Les pièces d’un projet Chaque projet s’ouvre sur la même barre d’onglets : **Général** (nom, description, partage et chats récents), **Chats** (tes chats dans le projet plus ceux qui lui sont partagés), **Discussions** (des fils par sujet pour toute l’équipe), **Tâches** (le tableau, avec sa vue **Métriques des tâches**), **Instructions** (du contexte qui s’applique à chaque chat du projet), **Connaissances** (les fichiers du projet, dans une arborescence de dossiers), **Agents et modèles** (les agents et modèles que les membres voient ici) et **Secrets**. Les apps installées dans le projet ajoutent leurs propres onglets à la suite. ## Pages dans cette section <CardGroup cols="2"> <Card title="Concepts de projet" icon="compass" href="/fr/platform/projects/concepts"> Le modèle mental — ce qu’un projet possède, quand il bat un chat isolé et comment le partage fonctionne. </Card> <Card title="Gérer les fichiers" icon="folder-open" href="/fr/platform/projects/manage-files"> L’onglet Connaissances — téléverser des fichiers dans des dossiers, le statut d’indexation et comment les fichiers du projet restent scopés au projet. </Card> <Card title="Agents et modèles" icon="bot" href="/fr/platform/projects/project-agents"> Choisir quels agents et modèles apparaissent dans un projet — Recommandés contre Restreints. </Card> <Card title="Discussions" icon="messages-square" href="/fr/platform/projects/discussions"> Des conversations d’équipe en fils, avec catégories, cycle de vie et des agents à une @mention. </Card> <Card title="Automatisation des tâches" icon="workflow" href="/fr/platform/projects/task-automation"> Affecter les tâches du tableau à des agents — la boucle d’exécution, le portail de revue et les garde-fous. </Card> <Card title="Backlog" icon="gauge" href="/fr/platform/projects/backlog"> Les tâches proposées qu’une automatisation ou un coéquipier a synchronisées — Démarrer les met sur le tableau, Fermer les écarte. </Card> </CardGroup> ## Où cela s’inscrit Les projets vivent à côté du Chat dans la barre latérale, et le passage de relais est naturel : une question démarre dans le Chat, se révèle plus grande qu’un chat et déménage dans un projet — l’action **Déplacer vers un projet…** du composeur transporte un chat existant. Si les projets sont nouveaux pour toi, commence par [Concepts de projet](/fr/platform/projects/concepts) pour le modèle, puis déroule [Utiliser les projets](/fr/tutorials/member/use-projects) de bout en bout sur un projet neuf. # Gérer les fichiers du projet Source: https://tale.dev/docs/fr/platform/projects/manage-files L’onglet **Connaissances** d’un projet est la zone de fichiers partagée que chaque chat du projet peut atteindre. Téléverse un fichier une fois et chaque chat du projet — et chaque agent qui y tourne — peut le lire sans nouveau téléversement. Cette page couvre l’arborescence de dossiers, le mécanisme de téléversement, l’épinglage et les limites. L’onglet Connaissances n’est pas la base de connaissances de l’organisation au sens de [Documents](/fr/platform/knowledge/documents). Ses fichiers sont scopés à un projet et n’apparaissent jamais dans la bibliothèque de l’organisation, dans les sélecteurs `@` hors du projet, ni via WebDAV ; supprimer le projet supprime les fichiers. Pour du matériel de référence à l’échelle de l’organisation, utilise [Documents](/fr/platform/knowledge/documents) et lie-les à des agents. <Frame caption="L’onglet Connaissances — l’arborescence de fichiers du projet ; chaque fichier reste borné à ce projet et indexé pour la recherche."> ![L’onglet Connaissances du projet Website relaunch montrant deux fichiers indexés dans l’arborescence, un bouton Nouveau dossier et la zone de dépôt Ajouter un fichier.](/images/platform/project-knowledge-files.webp) </Frame> ## Dossiers Les fichiers du projet vivent dans une arborescence de dossiers. **Nouveau dossier** en crée un à la racine ; l’icône dossier-plus sur une ligne de dossier crée un sous-dossier. Clique un dossier pour le sélectionner — la zone de dépôt passe à _Ajouter un fichier à « … »_ et les téléversements y atterrissent. Supprimer un dossier supprime tout son contenu, y compris les entrées des fichiers dans l’index de récupération ; la confirmation le dit avant que quoi que ce soit n’arrive. Les dossiers ici sont scopés au projet : un dossier homonyme dans la bibliothèque de l’organisation est un dossier différent. ## Un téléversement déroulé Ouvre le projet, clique **Connaissances**, sélectionne le dossier cible (ou aucun pour la racine), et glisse des fichiers sur la zone de dépôt. La ligne apparaît dans l’arborescence et passe à **Indexed** une fois que la récupération l’a intégrée. Le même téléversement est désormais accessible depuis n’importe quel chat que le projet possède : envoie un message qui référence le sujet et l’agent le récupère, ou tape `@` dans le composer et épingle le fichier — ou un dossier entier — au tour. ## Remplacer et supprimer Remplacer un fichier téléverse une nouvelle copie sous le même nom ; l’ancienne version passe dans l’historique de versions du projet. Les citations des chats antérieurs continuent de pointer vers la version qui était active quand le chat l’a référencée. Supprimer un fichier le retire du sélecteur immédiatement ; les chats existants gardent leurs citations, mais le fichier sous-jacent passe dans la [Corbeille](/fr/platform/admin/governance/trash) avec le reste de la cohorte de rétention du projet. ## Limites de taille Les limites par fichier et par projet sont fixées par l’organisation sous [Politiques et limites](/fr/platform/admin/governance/policies-and-limits). Atteindre une limite par fichier fait échouer le téléversement avec un toast ; atteindre une limite par projet le fait échouer avec un autre toast qui nomme la politique. Les membres qui atteignent une limite ne peuvent pas l’élever eux-mêmes — un Admin ajuste la politique, ou le propriétaire du projet supprime des fichiers plus anciens. ## Apparition dans les chats Un chat démarré à l’intérieur d’un projet a automatiquement accès à chaque fichier de l’onglet Connaissances du projet. L’outil de récupération de l’agent voit les fichiers du projet à côté de toute source de Connaissances liée à l’agent. Les citations issues de fichiers du projet sont scopées au chat qui les a produites — partager ce chat hors du projet préserve les citations, mais le visiteur ne peut pas cliquer vers la source à moins d’être lui aussi dans le projet. Épingler avec `@` resserre un seul tour : `@fichier` épingle un fichier, `@dossier` épingle un dossier et tout ce qu’il contient (le sélecteur propose les dossiers du projet dans les chats de projet, et les dossiers de l’organisation partout). Les fichiers épinglés sont aussi livrés dans la sandbox de l’agent sous `/user/uploads` — les agents de code comme Claude Code ouvrent donc les vrais octets au lieu de ne citer que des extraits de récupération. ## Où cela s’inscrit Gérer les fichiers est la page opérationnelle de l’onglet Connaissances — le cadrage conceptuel est sur [Concepts de projet](/fr/platform/projects/concepts), et l’équivalent lié à l’agent à l’échelle de l’organisation entière est [Documents](/fr/platform/knowledge/documents). Si tu te surprends à téléverser les mêmes fichiers dans plusieurs projets, c’est le signal pour les déplacer dans [Documents](/fr/platform/knowledge/documents) et lier un agent à la place. # Concepts de projet Source: https://tale.dev/docs/fr/platform/projects/concepts Un projet est l’unité que Tale sort quand un chantier a besoin des mêmes fichiers, des mêmes instructions et des mêmes surfaces de travail à travers beaucoup de chats et beaucoup de personnes. Cette page te donne le modèle mental — lis-la avant de créer ton premier projet, et reviens-y au moment de décider si un chat qui grossit mérite d’être promu en projet. <Frame caption="L’onglet Général — identité, partage et bandeau de statistiques sont la porte d’entrée du projet."> ![L’onglet Général du projet Website relaunch montrant les champs de nom et de description, la section de partage où l’équipe propriétaire est Toute l’organisation, et un bandeau de statistiques indiquant deux fichiers, aucun chat et Toute l’organisation.](/images/platform/project-general-tab.webp) </Frame> ## Ce qu’un projet possède Les **chats** démarrés dans le projet portent son contexte automatiquement. Ils restent les tiens jusqu’à ce que tu actives **Partager avec le projet** sur un chat — l’onglet Chats se divise en **Tes chats** et **Partagés avec le projet** en conséquence. Partager un chat masque tes souvenirs et tes instructions personnels dans les réponses que voient les autres membres. Les **instructions** sont du contexte qui s’applique à chaque chat du projet — le cadre, les contraintes et le vocabulaire du travail — pour que personne ne les recolle chat par chat. Les **fichiers** de l’onglet **Connaissances** sont le matériel de référence où chaque chat du projet peut puiser, rangés dans une arborescence de dossiers que tu remplis une fois plutôt que de les rattacher chat par chat. Ils restent scopés à ce projet — ils n’apparaissent jamais dans la bibliothèque de l’organisation ni dans les sélecteurs `@` hors du projet — voir [Gérer les fichiers](/fr/platform/projects/manage-files). Les **tâches et les discussions** font du projet un endroit où mener le travail, pas seulement en parler : un tableau avec des statuts et de l’[automatisation](/fr/platform/projects/task-automation), et des [discussions en fils](/fr/platform/projects/discussions) pour les décisions. **Agents et modèles** est une surface de curation : quels agents et modèles les membres voient en premier — ou voient tout court — dans ce projet ([Agents et modèles](/fr/platform/projects/project-agents)). ## Création et identité **Créer un projet** demande un nom et une **Clé du projet** — le préfixe des identifiants de tâches comme `WR-1`. La clé est fixe ; elle ne peut plus changer une fois le projet créé. La description, l’équipe propriétaire, l’icône et la couleur restent modifiables ensuite sur l’onglet **Général**, où les boutons unifiés **Enregistrer** et **Abandonner** siègent dans la barre d’onglets. ## Le modèle de partage Le partage se fait par équipe, pas par invitation individuelle. Un projet démarre en **Toute l'organisation** ; choisir une équipe propriétaire le limite à cette équipe, et d’autres équipes s’ajoutent sur l’onglet Général. Les admins de l’organisation ont toujours accès. Renommer, archiver et supprimer vivent dans le menu de ligne de la liste des projets — la suppression demande ce qu’il advient du contenu : détacher les fichiers et les chats (ils redeviennent des documents de bibliothèque et des chats personnels) ou les supprimer aussi. ## Quand y recourir | Choisis … quand | Projet | Chat isolé | | ---------------------------------------------------------- | ------ | ---------- | | Les mêmes fichiers servent à beaucoup de chats | ✓ | | | Les mêmes instructions s’appliquent à beaucoup de chats | ✓ | | | Plusieurs personnes travaillent le même chantier | ✓ | | | Le travail a des tâches, des responsables et des décisions | ✓ | | | La question est ponctuelle | | ✓ | Un chat isolé est la bonne forme pour explorer une réponse une fois. Dès que le contexte doit survivre au chat, déménage-le — l’action **Déplacer vers un projet…** du composeur transporte un chat existant dans un projet. ## Où cela s’inscrit Les projets sont la couture où se rejoignent les chats, les connaissances et l’automatisation des tâches. La lecture suivante naturelle est [Utiliser les projets](/fr/tutorials/member/use-projects), qui déroule un projet neuf de bout en bout ; les pages par onglet de cette section approfondissent les [fichiers](/fr/platform/projects/manage-files), les [agents et modèles](/fr/platform/projects/project-agents) et les [discussions](/fr/platform/projects/discussions). # Discussions Source: https://tale.dev/docs/fr/platform/projects/discussions Les **discussions** sont des conversations en fils qui vivent avec un projet, à côté de ses chats et de ses tâches. Utilise-les comme une équipe utilise un forum : ouvre un sujet, débats-en, résous-le — avec les agents du projet à une @mention. Elles réutilisent la surface de messages du chat, si bien qu’une discussion se lit et se compose comme un chat, mais elle appartient au projet et chaque membre du projet la voit, pas seulement son auteur. <Frame caption="L’onglet Discussions — chaque ligne porte sa catégorie et son statut de cycle de vie."> ![L’onglet Discussions du projet Website relaunch listant deux discussions ouvertes, l’une étiquetée Questions-réponses et l’autre Décisions.](/images/platform/project-discussions-list.webp) </Frame> ## Ouvrir une discussion Clique sur **Nouvelle discussion**, donne-lui un **Titre**, choisis une **Catégorie** et écris le message d’ouverture. Les catégories gardent le tableau lisible : **Général**, **Questions-réponses**, **Idées**, **Décisions**, **Annonces**, **Démos** et **Sondages**. Les réponses fonctionnent comme n’importe quelle zone de message — l’invite le dit : **Répondre… utilise @ pour mentionner un coéquipier ou un agent**. ## Les humains d’abord, les agents sur demande Les discussions sont d’abord humaines. Ton message est toujours enregistré comme un message entre personnes ; un agent ne répond que si tu en fais entrer un. - **@mentionne un agent** dans un message et cet agent répond dans le fil — le même routage et la même génération que dans le chat, visibles par tout le projet. - Sans @mention, rien n’est convoqué. Une discussion peut vivre sa vie entière sans qu’un agent ne parle jamais. Cela fait des discussions la bonne surface pour les décisions qui demandent une trace humaine avec un apport IA ponctuel — demande les données à l’agent en plein fil, puis décide autour. ## Cycle de vie La catégorie d’une discussion dit ce qu’elle est ; son statut dit où elle en est : - **Ouverte** — active, le statut par défaut. - **Résolue** — la question a sa réponse ou la décision est prise. **Rouvrir** la ramène à tout moment. - **Verrouillée** — plus aucune réponse ; le composeur est désactivé avec un avis de verrouillage. **Déverrouiller** l’inverse. Résoudre relève de la tenue de registre, pas de l’archivage — les discussions résolues restent lisibles et cherchables dans l’onglet. ## Transformer une discussion en travail **Créer une tâche** fait naître une tâche sur le tableau du projet depuis la discussion, reliée à la conversation dont elle vient — une décision prise en discussion devient du travail suivi sans la retaper. La discussion se souvient de la conversion : elle affiche **Convertie en tâche** avec un lien **Voir la tâche**, et elle ne peut être convertie qu’une seule fois. ## Où cela s’inscrit Les discussions comblent l’écart entre un chat personnel (une personne et un agent) et le tableau des tâches (du travail déjà décidé) : elles sont l’endroit où une équipe décide. Les tâches qu’elles font naître rejoignent l’[automatisation des tâches](/fr/platform/projects/task-automation) comme n’importe quelle tâche du tableau, et la mécanique des @mentions rejoint celle des [agents dans le chat](/fr/platform/chat/agents-in-chat). # Automatisation des tâches Source: https://tale.dev/docs/fr/platform/projects/task-automation Affecter une tâche du tableau à un agent IA la met au travail. Le **pack task-ops** — onze workflows en fichiers, provisionnés pour chaque organisation — couvre tout le cycle de vie : triage, exécution, revue, escalade, tenue des SLA et nettoyage. Chaque workflow est un simple fichier JSON que ton organisation possède : ajuste les seuils, édite les prompts ou désactive des déclencheurs individuels sur le workflow lui-même. Une tâche qu’une automatisation propose reste dans le [Backlog](/fr/platform/projects/backlog) jusqu’à ce qu’un humain la Démarre — à partir de ce moment, c’est une tâche de tableau comme une autre et elle entre dans la boucle ci-dessous. <Frame caption="Le tableau des tâches du projet — affecter une carte à un agent est ce qui lance la boucle ci-dessous."> ![Un tableau kanban de tâches dans le projet Website relaunch, montrant sept cartes de tâches réparties sur ses colonnes de statut, du Backlog et de À faire jusqu’à En revue, Terminé et Annulé.](/images/platform/projects-task-board.webp) </Frame> ## La boucle d’exécution 1. **Affecte** une tâche à un agent (ou laisse le _triage des non-affectées_ noter et router automatiquement les nouvelles tâches — les correspondances très sûres s’affectent seules, les autres reçoivent un commentaire de suggestion). 2. L’agent **accuse réception** (la tâche passe à _En cours_), travaille dans son propre fil de tâche avec les outils de tâches et publie son résultat en commentaire. 3. La tâche se gare en **_En revue_** — les agents ne peuvent jamais poser _Terminé_ ; la règle est appliquée côté serveur, quelle que soit la configuration des workflows. 4. Un humain **approuve** (le seul chemin automatisé vers _Terminé_) ou **demande des modifications** avec un retour, ce qui réengage le même agent sur le fil partagé et ouvre un nouveau portail de revue. Les revues se traitent depuis la fiche de tâche ou directement depuis la Boîte de réception. Les échecs ramènent la tâche à _À faire_ avec un commentaire d’explication. Quand une tâche racine décomposée a des sous-tâches, la tâche parente attend la fermeture de la dernière sous-tâche, puis remonte en _En revue_. ## Mentions, dépendances, échéances - **@-mentionne un agent** dans un commentaire ou dans la description d’une tâche et il lit le texte qui le mentionne, puis agit. Taper `@` ouvre une autocomplétion sur les membres et les agents du projet ; le composeur prévisualise si chaque agent mentionné répondra vraiment (automatisation coupée, budget épuisé, agent en pause). Modifier une description ne déclenche que les mentions nouvellement ajoutées, et ce que l’automatisation écrit elle-même ne déclenche jamais personne. - Quand un **bloqueur se ferme**, les tâches dépendantes reçoivent une note listant les bloqueurs restants ; le travail d’agent totalement débloqué redémarre seul, le travail humain reçoit une notification en boîte de réception. - Les **échéances** actionnent une échelle SLA : un avertissement 24 heures avant, une relance en cas de retard, puis une escalade humaine vers le créateur du projet et les admins de l’org — répétée une fois de plus si la tâche reste en retard. Chaque niveau ne tire qu’une fois ; repousser l’échéance réarme l’échelle. ## Garde-fous Chaque exécution d’agent — affectation, mention, révision, escalade, externe — passe le même portail d’admission : - **Budgets** (par agent, mensuels) : au seuil d’alerte, l’agent reçoit une consigne d’économie et les admins sont notifiés une fois ; au seuil de pause, les nouvelles exécutions sont refusées. Réinitialisation au changement de mois. - **Plafonds de simultanéité** (par agent et pour toute l’organisation) : les exécutions en trop font la file et démarrent seules quand une place se libère. - **Disjoncteur par tâche** : au-delà du nombre configuré d’exécutions par heure sur une même tâche, l’automatisation de cette tâche se met en pause jusqu’à ce qu’un humain change son statut. Les plafonds à l’échelle de l’organisation (simultanéité des exécutions, exécutions par tâche et par heure) sont des valeurs fixes de la plateforme ; le budget et le parallélisme par agent vivent dans la configuration de l’agent. ## Choisir le bon assigné Toutes les tâches ne sont pas faites pour un agent de code. La règle simple : | Forme de la tâche | Assigner | | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Recherche, rédaction, synthèses, livrables personnels | Une **personne** — désactive le tri des tâches non assignées sur les projets personnels pour que les agents ne s’en emparent pas tout seuls | | Automatisation générale avec les outils plateforme (commentaires, workflows, intégrations) | Un **Agent** (boucle d’outils plateforme) | | Travail de dépôt — bugs, fonctionnalités, refactorisations, PRs | Un **agent de code** avec le bon dispatch : tale-daemon (`runtime`) pour un espace de travail git, sandbox durable quand c’est configuré — ou accepte qu’un agent de code sandbox-seulement passe par la boucle plateforme sur le tableau tant que ces champs manquent | Le sélecteur d’assigné groupe les **Agents** et les **Agents de code** séparément et affiche un indice de dispatch d’une ligne pour chaque agent de code. Les agents d’image n’apparaissent pas dans la liste des assignés de tâches. ## L’arrêt d’urgence La politique de gouvernance `task_automation` porte l’interrupteur principal : la couper arrête le chemin d’exécution — le travail en vol se termine, rien de neuf ne démarre. Elle est réservée aux admins et auditée ; sur une instance auto-hébergée, la politique est l’un des fichiers de configuration de gouvernance de l’org, aux côtés des limites couvertes sur [Politiques et limites](/fr/platform/admin/governance/policies-and-limits). ## Où cela s’inscrit L’automatisation des tâches est ce qui transforme le tableau du projet d’une liste de choses à faire en une surface de délégation : un humain affecte ou approuve, le pack fait tourner tout ce qu’il y a entre les deux, et le portail de revue garde _Terminé_ comme décision humaine. La lecture suivante naturelle est [Backlog du projet](/fr/platform/projects/backlog) pour la façon dont le travail proposé entre dans la boucle, et [L’éditeur de workflow](/fr/platform/automations/editor) pour ajuster les workflows du pack lui-même. # Backlog du projet Source: https://tale.dev/docs/fr/platform/projects/backlog Une tâche au statut **`backlog`** est du travail proposé auquel personne ne s’est encore engagé — le plus souvent synchronisé par une automatisation comme [Trier les issues GitHub](/fr/platform/automations/builtin). Elle vit dans la **colonne la plus à gauche** du Tableau et la **section du haut** de la Liste, avec la même carte, la même fiche de détail, le même sélecteur de statut et le même sélecteur d’affectation que tout autre statut. [Automatisation des tâches](/fr/platform/projects/task-automation) couvre ce qui se passe une fois qu’une tâche atteint **À faire** et entre dans la boucle d’affectation. ## Une tâche synchronisée Trier les issues GitHub propose une tâche par issue ouverte exploitable, rattachée à l’issue pour qu’une synchronisation ultérieure ne la crée jamais en double : le titre est `#<numéro> <titre>` — par exemple `#482 Bouton de connexion mal aligné sur Safari` —, la description s’ouvre sur l’URL GitHub de l’issue elle-même, et ses étiquettes reflètent celles de l’issue sur GitHub. Une tâche que tu crées depuis le tableau avec le statut par défaut démarre à **À faire** ; choisis **Backlog** dans le formulaire de création pour déposer toi-même une proposition. ## Faire avancer le travail Il n’y a pas de boutons réservés au backlog. Glisse une carte vers une autre colonne, ouvre la fiche de détail et choisis un nouveau statut, ou affecte un responsable — les mêmes chemins que pour **À faire** ou **En cours**. L’auto-affectation et les suggestions d’affectation par agent ne tournent qu’à **À faire**, pas tant que la tâche reste en **Backlog**. Si tu passes une proposition directement à **En cours** ou si tu l’affectes à la main, tu prends la responsabilité toi-même. Écarte une proposition comme toute autre tâche : passe le statut à **Annulé** dans le sélecteur. Une annulation humaine tient — une synchronisation GitHub ultérieure ne ressuscite pas une proposition que tu as rejetée tant que l’issue reste ouverte sur GitHub. Quand une tâche était **Terminée** sur le tableau et que quelqu’un rouvre l’issue sur GitHub, la synchronisation la remet en **Backlog**. ## Où cela s’inscrit Le backlog est la colonne d’entrée entre une automatisation qui propose du travail et ton équipe qui s’y engage. La lecture suivante naturelle est [Automatisation des tâches](/fr/platform/projects/task-automation) pour ce qui se passe à **À faire**, ou [Automatisations livrées](/fr/platform/automations/builtin) pour ce qui propose des tâches en premier lieu. # Agents et modèles dans un projet Source: https://tale.dev/docs/fr/platform/projects/project-agents L’onglet **Agents et modèles** d’un projet décide quels agents et modèles les membres rencontrent quand ils discutent dans le projet. Il ne crée pas de nouveaux agents — les agents se construisent au niveau de l’organisation sous [Agents](/fr/platform/agents/concepts) — il organise le catalogue existant pour le contexte de ce projet, pour qu’un membre qui ouvre le sélecteur voie d’abord les bons outils pour le travail. <Frame caption="L’onglet Agents et modèles — un choix Recommandés/Restreints pour les agents, un pour les modèles."> ![L’onglet Agents et modèles d’un projet montrant deux groupes de boutons radio, Agents et Modèles, offrant chacun un mode Recommandés et un mode Restreints avec un bouton d’ajout.](/images/platform/project-agents-models.webp) </Frame> ## Les deux modes Les agents et les modèles s’organisent séparément, chacun avec les deux mêmes modes : - **Recommandés** — les éléments que tu listes sont épinglés en haut du sélecteur ; tout ce que le membre pourrait normalement utiliser reste disponible en dessous. C’est le mode par défaut, et le bon pour orienter sans bloquer. - **Restreints** — seuls les éléments que tu listes sont disponibles dans ce projet. Un membre qui choisit autre chose reçoit un refus clair : le composeur signale que l’agent ou le modèle n’est pas disponible dans ce projet et lui demande d’en choisir un autre. L’ordre de la liste est l’ordre que voient les membres, et le premier élément est celui par défaut — glisse pour réordonner. **Ajouter un agent** et **Ajouter un modèle** étendent la liste. <Warning> En mode **Restreints**, une liste vide interdit le chat du projet à chaque membre — il ne reste rien à choisir. Ajoute au moins un élément avant d’enregistrer, ou rebascule sur **Recommandés**. </Warning> ## Ce que vivent les membres Dans le projet, le sélecteur d’agent et le sélecteur de modèle du composeur reflètent la curation — les éléments recommandés d’abord, les éléments restreints seulement. Un chat déplacé dans le projet avec un agent désormais interdit ne casse pas en silence : l’envoi est refusé avec le message d’agent non disponible, et le membre en choisit un autorisé. Hors du projet, rien ne change ; la curation se limite aux chats qui tournent dans le contexte du projet. ## Qui peut le modifier La modification de l’onglet suit les rôles de l’organisation : un rôle d’éditeur ou d’admin est requis pour enregistrer, et les membres qui ne l’ont pas voient le projet en lecture seule, avec un bandeau qui les renvoie vers un éditeur du projet. Les changements passent par **Enregistrer** dans la barre d’onglets — le même bloc unifié Enregistrer/Abandonner que les onglets Général et Instructions. ## Quand recourir à chaque mode | Choisis … quand | Recommandés | Restreints | | ----------------------------------------------------------- | ----------- | ---------- | | Le bon agent doit être le premier choix évident | ✓ | | | Les membres doivent garder l’accès au catalogue complet | ✓ | | | La conformité ou les coûts exigent une liste courte et fixe | | ✓ | | Un modèle coûteux ne doit pas servir à ce travail | | ✓ | ## Où cela s’inscrit Cet onglet est la curation côté projet d’un catalogue côté organisation : construire les agents, leurs instructions et leurs connaissances est le travail de la section [Agents](/fr/platform/agents/concepts) ; décider lesquels ce projet met en avant est le tien. Pour le comportement du sélecteur dans un chat, lis [Agents dans le chat](/fr/platform/chat/agents-in-chat). # Développeur Source: https://tale.dev/docs/fr/platform/developer/overview Développeur est la surface en-app pour les personnes qui câblent Tale au reste de leur pile. Elle regroupe les quatre leviers qui laissent du code externe parler à Tale et Tale parler à du code externe : clés API pour la surface REST, tools personnalisés qui étendent la portée d’un agent, webhooks d’agent pour les déclencheurs entrants, et serveurs MCP pour le pont processus-externe. Les personnes de rôle Développeur voient ce menu ; les Membres et Éditeurs ne le voient pas. Cette vue d’ensemble nomme ce que couvre chaque page et pointe vers la référence plus profonde. Les utilisateurs de rôle Développeur atterrissent typiquement ici à leur premier jour, montent les identifiants et tools dont ils ont besoin, et reviennent quand ils étendent la pile — ajouter un nouveau serveur MCP, roter une clé, enregistrer un nouveau webhook. ## Ce que couvre Développeur La surface Développeur s’asseoit à côté du reste des paramètres de l’org mais avec une audience plus étroite. Elle suppose que tu sais ce qu’est une API REST, à quoi ressemble un webhook, et ce que fait un serveur MCP — les pages ne réexpliquent pas les concepts sous-jacents ; elles expliquent comment Tale les expose. La même surface dans les onglets Cloud et self-hosted ne diffère que par la forme de déploiement ; l’UI ici est identique. Les équivalents fichier-de-configuration de certaines de ces fonctionnalités (variables d’environnement, configs JSON pour tools personnalisés) vivent un onglet plus loin dans la documentation self-hosted. ## Pages dans cette section <CardGroup cols="2"> <Card title="Clés API" icon="key" href="/fr/platform/admin/api-keys"> Câbler un script, une tâche cron, ou un service interne à l’API REST de Tale. Partagée avec Admin sous Paramètres > Clés API. </Card> <Card title="Serveurs MCP" icon="server" href="/fr/platform/integrations/mcp-servers"> Enregistrer un processus externe protocole MCP et choisir quels de ses tools les agents de l’org peuvent appeler. </Card> <Card title="Déclencheurs webhook d’agent" icon="webhook" href="/fr/platform/agents/webhook-triggers"> Déclencher un agent spécifique depuis un système externe sur un POST entrant. </Card> <Card title="Tools d’agent" icon="wrench" href="/fr/platform/agents/tools"> Étendre le toolbelt d’un agent avec un tool personnalisé que les agents de l’org peuvent appeler. </Card> </CardGroup> ## Où cela s’inscrit Développeur est le pont entre Tale et le reste de la base de code que l’org fait tourner. La première lecture naturelle dépend de ce que tu viens câbler — pour sortant (quelque chose dans Tale appelle dehors) [Tools d’agent](/fr/platform/agents/tools) et [Serveurs MCP](/fr/platform/integrations/mcp-servers) ; pour entrant (quelque chose dehors appelle dans Tale) [Clés API](/fr/platform/admin/api-keys) et [Déclencheurs webhook d’agent](/fr/platform/agents/webhook-triggers). # Créer un agent Source: https://tale.dev/docs/fr/platform/agents/create Ce tutoriel va d’un dialogue **Créer un agent** vide à un agent que tu publies et utilises. Le résultat est un agent qui connaît son domaine, a les outils pour agir sur ce qu’il lit, et reste joignable depuis n’importe quel chat de ton organisation. Compte une quinzaine de minutes si un fournisseur de modèles est déjà configuré ; davantage s’il faut aussi en mettre un en place. Le tutoriel prend un agent de tri de support comme exemple filé — le même que celui qu’introduit [Concepts d’agent](/fr/platform/agents/concepts). Remplace librement par ton propre domaine ; les étapes ne dépendent pas de l’exemple. ## Avant de commencer Vérifie que deux choses sont en place : - Un fournisseur de modèles est configuré sous **Paramètres > Fournisseurs**. Les utilisateurs Cloud en ont un par défaut ; les opérateurs auto-hébergés suivent [Configuration → fournisseurs](/fr/self-hosted/configuration/providers). Sans lui, le dialogue t’arrête : un agent a besoin d’un modèle pour tourner. - Tu détiens le rôle Éditeur ou supérieur dans cette organisation. En cas de doute, vérifie ta ligne de membre sous **Paramètres > Organisation**. ## Étape 1 — Créer l’agent Ouvre **Agents** dans la barre latérale et clique sur **Créer un agent**, puis choisis **Vierge** (le menu propose aussi **À partir d'un modèle** et **Téléverser un fichier** pour importer du JSON d’agent). Le dialogue demande quatre choses : un **Nom** — l’identifiant unique utilisé dans les liens et l’API, que tu ne peux plus changer ensuite ; utilise uniquement des lettres minuscules, des chiffres, des tirets et des underscores, par exemple `seo-writer` — un **Nom d'affichage** que tes coéquipiers voient dans le chat, une **Description**, et la liste **Modèle**. Le premier modèle est celui par défaut et les suivants sont des fallbacks ; glisse pour réordonner ou ajoutes-en d’autres à tout moment. Clique sur **Continuer** et l’éditeur s’ouvre sur l’onglet **Général**. <Frame caption="La liste des agents — Créer un agent se trouve en haut à droite."> ![La liste des agents avec le dossier chat déplié, montrant les lignes Assistant et Automation Assistant avec leurs modèles par défaut et le nombre d’outils.](/images/platform/agents-list-expanded.webp) </Frame> ## Étape 2 — Écrire les instructions Ouvre **Instructions et modèles**. Le champ **Instructions système** est du markdown pur, avec **Parcourir les prompts** pour partir de la bibliothèque de prompts de l’organisation et des variables de template résolues à l’exécution. Trois conseils venus du terrain : - **Ouvre par la voix.** Un paragraphe qui nomme qui est l’agent, à qui il répond et quel ton il adopte. Le modèle traite cela comme le signal le plus fort. - **Nomme explicitement les cas de refus.** Trois ou quatre phrases qui disent ce que l’agent refuse de faire et ce qu’il dit quand il refuse. - **Résiste à l’envie de tout spécifier.** De longues instructions se diluent dans les longues conversations. Si un comportement relève du code, appuie-toi sur un outil ; s’il relève des données, appuie-toi sur les connaissances. Le même onglet contient la liste de modèles fixée dans le dialogue — le premier modèle est le primaire, et chaque modèle en dessous est le fallback suivant quand celui du dessus est indisponible. <Frame caption="Instructions et modèles — le prompt système au-dessus, la liste ordonnée de modèles en dessous."> ![L’onglet Instructions et modèles de l’éditeur d’agent, montrant le champ d’instructions système avec ses onglets de langue et une liste ordonnée de cinq modèles avec leurs contrôles de réordonnancement.](/images/platform/agent-editor-instructions.webp) </Frame> ## Étape 3 — Cadrer ses connaissances Passe à l’onglet **Base de connaissances**. Choisis un **Mode de récupération** — **Outil** laisse l’agent chercher à la demande, **Contexte** injecte les connaissances pertinentes dans chaque réponse, **Les deux** fait les deux, **Désactivé** coupe la base de connaissances. Cadre ensuite ce qui est interrogeable : **Inclure les documents de l'équipe**, **Inclure les documents de l'organisation**, et les **Documents de l'agent** que tu téléverses pour cet agent seul. Lie le plus petit ensemble utile — tout ce que tu inclus concourt à la récupération à chaque question. <Frame caption="L’onglet Base de connaissances — le mode de récupération, les portées de documents et les documents d’organisation indexés."> ![L’onglet Base de connaissances de l’éditeur d’agent avec Outil choisi comme mode de récupération, les interrupteurs des documents d’équipe et d’organisation tous deux actifs, et la liste des documents de l’organisation où chaque fichier porte un badge Indexé.](/images/platform/agent-editor-knowledge.webp) </Frame> ## Étape 4 — Accorder les outils Passe à l’onglet **Outils**. Les outils sont des cases à cocher individuelles groupées par catégorie — clients, produits, fichiers, workflows et plus — plus un sélecteur de mode **Recherche web** en haut. Accorde ce dont l’agent a besoin et laisse le reste éteint ; chaque case cochée élargit la frontière de confiance. <Frame caption="L’onglet Outils — une liste de cases par outil, groupée en cartes de catégorie, chacune comptant ce qu’elle a accordé."> ![L’onglet Outils de l’éditeur d’agent, défilé jusqu’aux cartes de catégorie, avec Connaissances à trois outils cochés sur quatre et Fichiers à sept sur sept, tandis que Conversations, Discussions, Analytique et Tâches et projets n’ont rien d’accordé.](/images/platform/agent-editor-tools.webp) </Frame> <Note> **Exécuter du code** (sous **Système**) exécute des scripts dans une sandbox et relève de la [politique run-code](/fr/platform/admin/governance/run-code-policy) de l’organisation — la case accorde l’outil, la politique décide de ce qu’une exécution peut faire. </Note> ## Étape 5 — Le rendre visible et l’essayer De retour sur **Général**, active **Visible dans le chat** et clique sur **Enregistrer**. Un toast confirme **Agent enregistré**. Ouvre un nouveau chat, choisis l’agent dans le sélecteur et envoie un message qui sollicite les connaissances et les outils accordés. Si l’agent répond comme tu l’as écrit, c’est terminé ; sinon, le bouton **Historique** en haut à droite de l’éditeur montre chaque version enregistrée et te laisse comparer ou restaurer. ## Dépannage - **L’enregistrement échoue avec un avertissement de modèle.** L’agent n’a aucun modèle — ajoutes-en un sur l’onglet Instructions et modèles avant d’enregistrer. - **L’agent n’apparaît pas dans le sélecteur du chat.** Confirme que **Visible dans le chat** est activé ; éteint, l’agent n’est joignable que par délégation. S’il est activé, regarde la section **Accès** — un agent assigné à une équipe n’est utilisable que par cette équipe. - **Les réponses ignorent les connaissances.** Le mode de récupération est peut-être **Désactivé**, les interrupteurs de portée éteints, ou le document pas encore **Indexé** — ouvre-le depuis [Documents](/fr/platform/knowledge/documents) pour vérifier. - **Un appel d’outil est refusé à l’exécution.** Une politique de gouvernance verrouille l’outil : la définition de l’agent l’autorise, l’exécution le refuse. Regarde [Politiques et limites](/fr/platform/admin/governance/policies-and-limits). ## Où ça sert ensuite Créer un agent est le moment où le reste de la plateforme commence à sentir comme Tale plutôt que comme un chat générique. La marche suivante naturelle est [Agent avec connaissances](/fr/tutorials/editor/agent-with-knowledge) — même forme, mais lie un dossier de PDF et exerce la pipeline de citations de bout en bout. Pour voir un agent confier une sous-tâche à un worker, [Confier du travail à un worker](/fr/tutorials/editor/delegate-between-agents) est le parcours. # Concepts d’agent Source: https://tale.dev/docs/fr/platform/agents/concepts Un agent est l’unité vers laquelle Tale se tourne quand la même question va revenir. C’est la combinaison à quatre boutons — instructions, connaissances, outils et modèle — les quatre choses que tu changes pour faire varier son comportement. Les Éditeurs et les Développeurs les construisent ; les Membres et les autres rôles les exécutent. Cette page te donne le modèle mental que le reste de la section présuppose. Lis-la une fois avant de construire ton premier agent ; reviens-y quand tu ne sais plus si un comportement à changer vit dans les instructions, les connaissances, les outils ou le modèle. ## Les quatre boutons Les **instructions** sont le prompt système — la prose qui encadre chaque réponse. Garde-les courtes, opiniâtres et concrètes ; de longues instructions se diluent dans les longues conversations. Précise la voix, les contraintes et les cas de refus. Les **connaissances** sont ce que l’agent peut récupérer depuis la base de connaissances de l’organisation. Un mode de récupération décide si l’agent cherche à la demande, reçoit les extraits pertinents injectés dans chaque réponse, fait les deux, ou rien — et des interrupteurs de portée décident si les documents d’équipe, les documents d’organisation et les documents téléversés pour l’agent lui-même sont interrogeables. Une connaissance hors de ces portées est invisible pour l’agent — il n’y a pas de tirage implicite sur tout ce que possède l’organisation. Les **outils** sont ce que l’agent peut faire au-delà de répondre par du texte. L’onglet **Outils** de l’agent est une liste de cases à cocher, outil par outil, groupée par catégorie — données clients et produits, fichiers, workflows, recherche web, exécution de code, et plus. Active chaque outil individuellement ; chaque outil accordé élargit la frontière de confiance, donc garde la liste courte. Le **modèle** est le LLM derrière chaque réponse. Les modèles forment une liste ordonnée : la première entrée est le primaire, et les suivantes sont des fallbacks que Tale essaie dans l’ordre quand le primaire est indisponible. Changer de modèle ne ré-entraîne rien — les trois autres boutons de l’agent sont la « mémoire » que le modèle a du travail. ```mermaid flowchart LR I[Instructions] --> A((Agent)) K[Connaissances] --> A T[Outils] --> A M[Modèle] --> A A --> R[Réponse avec citations] ``` ## Les skills comme bundle Un skill empaquette des instructions — et optionnellement des scripts et des fichiers de référence — dans un bundle réutilisable que tu lies à un agent. Va vers un skill quand le même motif apparaît sur plusieurs agents : une voix d’écriture, un calcul, une tâche en plusieurs étapes. Les skills composent avec les quatre boutons ; un agent peut en lier jusqu’à dix et lit chacun à l’exécution. La page des skills détaille l’arbitrage entre un skill et des instructions inline : voir [Skills d’agent](/fr/platform/agents/skills). ## Mis bout à bout — un agent de tri du support Un premier agent utile est celui du tri de support : il lit la question entrante, répond à ce qu’il peut et escalade le reste. Les quatre boutons : - Instructions : une voix en un paragraphe, plus trois cas de refus explicites. - Connaissances : la récupération à la demande sur la documentation produit ; rien de téléversé côté agent. - Outils : la recherche web et les outils de conversation. Pas d’exécution de code. - Modèle : un primaire capable, avec un fallback moins cher juste après dans la liste. La conversation coule ensuite : message de l’utilisateur → les instructions cadrent la réponse → la récupération de connaissances trouve les extraits pertinents → les outils comblent les trous → la réponse arrive avec ses citations. Escalader vers un spécialiste n’est pas un interrupteur d’outil — cela suit les relations de délégation entre agents. Voir [Agents workers](/fr/platform/agents/delegation). ## Quand y recourir Un agent seul est la bonne forme quand la conversation reste dans un domaine et une voix. Va vers une [automatisation](/fr/platform/automations/concepts) quand le travail est multi-étapes et que tu veux des approbations ou de la planification entre les étapes ; va vers un chat brut (sans agent) quand tu explores une réponse toi-même et que les réglages par défaut du modèle suffisent. | Utilise … quand | Agent | Chat brut | Automatisation | | --------------------------------------------------------------- | ----- | --------- | -------------- | | La même question revient | ✓ | | | | La voix ou les contraintes comptent | ✓ | | | | Il te faut des approbations ou de la planification entre étapes | | | ✓ | | Tu explores une réponse une seule fois | | ✓ | | ## Construis-en un Les quatre boutons sont ce dont chaque agent Tale est fait : changes-en un et tu as changé le comportement de l’agent, changes-en trois et tu as fabriqué un nouveau produit. La lecture suivante naturelle est [Construis ton premier agent](/fr/tutorials/editor/first-agent-end-to-end) — elle parcourt les quatre boutons de bout en bout sur une instance neuve. # Génération d’images Source: https://tale.dev/docs/fr/platform/agents/image-generation N’importe quel assistant dans Tale peut générer des images. Demande-lui de créer, dessiner ou concevoir quelque chose et il produit l’image inline, comme une pièce jointe s’affiche dans la réponse — il n’y a aucun mode séparé à activer d’abord. Cela fonctionne dès que l’espace de travail a un modèle de génération d’images configuré ; cette page couvre le câblage. La mécanique dépend du fournisseur sous-jacent — qualité, coût et vitesse varient largement. Le travail de Tale est d’exposer la capacité à l’agent et à l’utilisateur ; celui du fournisseur, de fabriquer l’image. ## Demander une image à n’importe quel assistant Chaque assistant porte un outil d’image qu’il saisit quand tu lui demandes de créer une image, un logo ou une illustration. L’assistant appelle l’outil, l’image s’affiche inline, et son texte s’enroule autour du résultat comme il le ferait autour d’une pièce jointe téléversée. Parce que l’outil est livré avec chaque assistant, l’assistant **Auto** prend aussi en charge une demande d’image — tu n’as pas à choisir d’abord un agent spécialisé. L’image vient du modèle de génération d’images de l’espace de travail — celui qu’un admin a mis en place sous [Fournisseurs](/fr/platform/admin/providers) et étiqueté **Génération d'images**. Il n’y a rien à configurer par agent. Quand l’espace de travail n’a pas de tel modèle, l’assistant te dit que la génération d’images est indisponible au lieu de deviner, pour qu’un admin sache qu’il faut en ajouter un. ## Les surfaces d’image dédiées Deux formes plus lourdes existent au-delà de l’outil inline. Dans l’éditeur d’agent, l’outil lui-même est **Générer une image** sous la catégorie **Images** de l’onglet Outils — décoche-le pour un agent qui ne doit jamais produire d’images. Et le type d’un agent (sur l’onglet **Général**) peut être réglé sur **Génération d'images**, ce qui route chaque message droit vers un modèle d’image — la forme derrière l’agent **Créateur d'images** du catalogue, qui génère et retouche des images à partir de prompts texte. Va vers le type dédié quand tout le travail de l’agent est l’imagerie ; laisse l’outil inline à tous les autres. ## Comment ça s’affiche Quand l’agent génère une image, la réponse l’affiche inline à côté de son texte. Survoler montre une petite pastille **Aperçu de l'image** ; cliquer ouvre l’aperçu en taille réelle avec les contrôles **Image précédente** et **Image suivante** si la réponse en a produit plusieurs. L’image est stockée dans le magasin d’objets du chat, à côté des pièces jointes, et hérite des règles de rétention du chat. ## Coût et budget Les modèles d’image coûtent plus cher par appel que les modèles de texte — parfois dix fois plus. Les [Politiques et limites](/fr/platform/admin/governance/policies-and-limits) de l’organisation peuvent plafonner le coût d’image par utilisateur, par équipe ou par agent ; atteindre le plafond se manifeste par un toast et l’image ne s’affiche pas. Le coût est visible dans les [analyses d’utilisation](/fr/platform/admin/governance/usage-analytics), dans le même tableau Top Models que les modèles de texte. ## Où ça se situe La génération d’images repose sur une seule chose — un modèle étiqueté **Génération d'images** dans l’espace de travail — et à partir de là chaque assistant peut produire une image inline, l’assistant **Auto** compris. Le candidat à la dérive ici, ce sont les noms de fournisseurs et de modèles ; couple cette page avec la liste vivante des modèles sous [Fournisseurs](/fr/platform/admin/providers) plutôt que de mémoriser des chaînes de modèles précises. # Amorces de conversation Source: https://tale.dev/docs/fr/platform/agents/conversation-starters Une amorce est un court prompt suggéré que l’agent affiche sur un écran de chat vide. Touches-en une et le texte tombe dans la zone de saisie ; l’utilisateur le modifie s’il veut, puis envoie. Les amorces sont les points d’entrée choisis par l’auteur de l’agent vers ce pour quoi l’agent existe — cette page est le côté auteur ; leur rendu côté utilisateur est [Amorces et prompts](/fr/platform/chat/starters-and-prompts). <Frame caption="L’onglet Amorces — une liste ordonnée de prompts avec les onglets de langue au-dessus."> ![L’onglet Amorces de l’éditeur d’agent montrant quatre amorces de conversation en anglais avec leurs poignées de glissement, leurs flèches de réordonnancement et leurs boutons de suppression.](/images/platform/agent-editor-starters.webp) </Frame> ## Ajouter et ordonner les amorces Ouvre l’agent et passe à l’onglet **Amorces**. Chaque amorce est un prompt d’au plus 200 caractères ; **Ajouter une amorce** ajoute une ligne, jusqu’à quatre par agent — laisse la liste vide pour n’afficher aucune suggestion. L’ordre compte parce que c’est l’ordre que voient les utilisateurs : glisse la poignée d’une ligne ou utilise les flèches pour la déplacer, et retire-en une avec le × de sa ligne. Clique sur **Enregistrer** — les amorces voyagent avec la configuration de l’agent comme n’importe quel autre réglage. Écris les amorces comme un utilisateur poserait vraiment sa question : concret, à la première personne, dans le domaine de l’agent. Quatre prompts vagues se lisent moins bien que deux prompts nets. ## Les traduire Chaque amorce a une version par défaut (l’onglet marqué **par défaut**) et une traduction optionnelle par langue. Un onglet de langue auquel il manque encore sa version est signalé **non traduit**, et les utilisateurs de cette langue voient le texte par défaut. Passe sur un onglet de langue pour saisir les traductions à la main — les traductions recouvrent les lignes existantes ; la liste elle-même (nombre et ordre) appartient à la langue par défaut. **Traduction automatique** sur un onglet de langue remplit les versions manquantes en une étape. Les résultats s’enregistrent comme des chaînes ordinaires, modifiables, donc ajuste-les ensuite là où la tournure machinale manque ta voix ; si la traduction échoue, un toast le dit et les valeurs par défaut restent en place. ## Où ça se situe Les amorces de conversation sont la plus petite surface de la zone des agents — quelques phrases chacune, mais elles décident si l’écran de chat vide a l’air engageant ou nu. La page à coupler avec celle-ci est [Amorces et prompts](/fr/platform/chat/starters-and-prompts), qui montre leur rendu côté utilisateur ; le reste du comportement de l’agent vit dans [Concepts d’agent](/fr/platform/agents/concepts). # Webhooks d’agent Source: https://tale.dev/docs/fr/platform/agents/webhook-triggers L’onglet **Webhooks** d’un agent crée des URL uniques que des systèmes externes peuvent appeler en POST pour chatter avec l’agent — rien de l’interface n’est impliqué. Va vers lui quand quelque chose hors de Tale a besoin que l’agent réponde : un bot Slack, un gestionnaire de formulaire, un job planifié. Cette page couvre la seule surface webhook par agent. Pour les déclencheurs entrants qui lancent un workflow plutôt qu’un agent, voir [Workflows → déclencheurs](/fr/platform/automations/triggers) ; pour la surface développeur complète, voir [Développer → référence API](/fr/develop/api-reference). <Frame caption="L’onglet Webhooks — un webhook en service avec son interrupteur Actif et l’heure du dernier déclenchement."> ![L’onglet Webhooks de l’éditeur d’agent montrant le bouton Créer un webhook et un tableau avec une URL de webhook, un interrupteur actif et un dernier déclenchement encore à jamais.](/images/platform/agent-editor-webhooks.webp) </Frame> ## Créer un webhook Ouvre l’agent, passe à **Webhooks** et clique sur **Créer un webhook**. Le dialogue montre la nouvelle URL une seule fois — mets-la de côté, parce que le token embarqué dans l’URL fait office d’identifiant d’authentification. Il n’y a ni clé API séparée ni en-tête : quiconque détient l’URL peut chatter avec l’agent, donc traite-la comme un secret. ## L’appeler Envoie un POST avec un corps JSON portant un champ `message` ; la réponse est celle de l’agent : ```bash curl -X POST https://tale.yourcompany.com/api/agents/wh/<token> \ -H "Content-Type: application/json" \ -d '{"message": "Hello"}' ``` Trois champs façonnent l’appel : - **`stream`** — ajoute `"stream": true` et la réponse arrive en server-sent events au lieu d’une seule réponse JSON. - **`threadId`** — sans lui, chaque POST démarre une conversation neuve ; passe l’identifiant de fil d’une réponse précédente pour en continuer une avec son contexte intact. - **Fichiers** — envoie du `multipart/form-data` avec un champ `message` et un ou plusieurs champs `file` pour joindre des fichiers au message. L’action **Exemples d'utilisation** de chaque ligne ouvre des exemples prêts à l’emploi pour tout cela, remplis avec la vraie URL de la ligne. ## Le point de terminaison compatible OpenAI Ajouter `/chat/completions` à l’URL du webhook expose un point de terminaison ChatCompletion à la OpenAI, pour que les clients OpenAI du commerce puissent pointer sur un agent : utilise l’URL du webhook comme URL de base, n’importe quelle valeur non vide comme clé API, et un identifiant de modèle de la liste de l’agent (les valeurs inconnues retombent sur le modèle par défaut). Les téléversements de fichiers ne sont pris en charge que sur l’URL de base du webhook, pas sur ce sous-chemin. ## Gérer et révoquer Le tableau montre l’URL de chaque webhook, un interrupteur **Actif** et le moment de son dernier déclenchement. Éteindre un webhook le met en pause sans perdre l’URL ; le supprimer est le geste de révocation — tout système qui utilise encore cette URL perd l’accès, donc provisionne le webhook de remplacement avant de retirer l’ancien. ## Où ça se situe Les webhooks sont la surface d’intégration légère, par agent — juste quand l’intégration est « cet agent répond à cette seule chose ». Pour des flux plus riches avec des étapes et des approbations, modélise le travail comme une [automatisation](/fr/platform/automations/concepts) et pointe l’appelant sur le déclencheur webhook de l’automatisation — [Déclencher une automatisation par webhook](/fr/tutorials/developer/trigger-automation-via-webhook) parcourt cette forme de bout en bout. # Dossiers d’agents Source: https://tale.dev/docs/fr/platform/agents/categories Les agents se regroupent par dossiers, et un dossier vient de l’identifiant de l’agent : un agent dont l’identifiant est `github/review-pull-requests/pr-reviewer` se range sous un dossier `github/review-pull-requests` partout où les agents sont listés. Les dossiers sont un outil de rangement, pas une frontière de permission — qui peut utiliser un agent relève de la section **Accès** de sa page **Général**, inchangée par l’endroit où il est rangé. <Frame caption="La liste des agents avec le dossier chat déplié — le dossier est le préfixe du slug, les lignes sont ses agents."> ![La liste des agents montrant les agents du dossier chat — Assistant et Automation Assistant —, chacun avec son badge de type, son modèle par défaut et son nombre d’outils.](/images/platform/agents-list-expanded.webp) </Frame> ## Ranger un agent dans un dossier Les identifiants avec dossier viennent de la plateforme, pas du dialogue de création. Le champ **Nom** du dialogue prend un identifiant plat — minuscules, chiffres, traits d’union et tirets bas, sans `/` —, si bien qu’un agent créé là atterrit non rangé, au niveau supérieur. Le préfixe de dossier (`chat/`, `github/review-pull-requests/`) est réservé aux agents que la plateforme fournit ou installe : les builtins arrivent déjà rangés, et l’installation d’une [automatisation](/fr/platform/automations/concepts) range ses agents dans le dossier que leur identifiant nomme. Un identifiant ne change plus ensuite, le dossier est donc fixé à la création. Le nom d’affichage est indépendant ; renomme l’agent librement sans le déplacer. Dans la liste **Agents**, les dossiers s’affichent comme des lignes repliées avec un compte d’agents — clique sur l’une d’elles pour la déplier, et le fil d’Ariane suit où tu es. Les agents intégrés arrivent pré-rangés : les assistants généralistes sous `chat` ; les agents installés avec une automation se rangent dans le dossier de leur automation. ## Des agents qui arrivent avec une automatisation Installer une [automatisation](/fr/platform/automations/concepts) range ses agents comme tous les autres — le PR Creator et le PR Reviewer du bundle « Résoudre les issues GitHub » atterrissent dans la même liste, dans le dossier que nomme leur identifiant. Il n’existe pas de boutique d’agents à part : le [catalogue des automatisations](/fr/platform/automations/catalog) est l’endroit d’où viennent les agents groupés, et la liste est l’endroit où ils vivent ensuite. <Note> Le sélecteur du chat ne groupe pas par dossier — c’est une liste cherchable, avec **Auto** en tête, qui montre chaque agent activé et visible dans le chat ; les agents de code se rangent dans leur propre section **Agents de code**. </Note> ## Quand y recourir | Utilise les dossiers quand… | Utilise l’accès d’équipe quand… | | --------------------------------------------------- | --------------------------------------------------------- | | La liste des agents s’allonge et demande de l’ordre | Un agent ne doit être utilisable que par une seule équipe | | Chaque département possède son lot d’agents | Tu traces une frontière de permission, pas un annuaire | ## Où ça se situe Les dossiers sont le regroupement le plus léger disponible pour les agents — ils trient la liste et le catalogue, rien de plus. Les séparations plus grandes vivent ailleurs : [Agents de projet](/fr/platform/projects/project-agents) cantonnent un agent à un Projet, et [Politiques et limites](/fr/platform/admin/governance/policies-and-limits) gouvernent ce que n’importe quel agent peut dépenser ou faire. # Skills d’agent Source: https://tale.dev/docs/fr/platform/agents/skills Un skill est l’unité vers laquelle Tale se tourne quand le même motif apparaît sur plusieurs agents. C’est un bundle réutilisable — un `SKILL.md` avec des instructions, plus des scripts, références et assets optionnels — qui vit dans la bibliothèque de skills de l’organisation et que les agents lisent à l’exécution. Lie le même skill à trois agents et tu maintiens le comportement à un seul endroit. Cette page te donne le modèle mental pour savoir quand un skill est le bon geste et quand des instructions inline le sont. Lis-la avant de téléverser ton premier skill ; reviens-y quand les instructions d’un agent s’allongent et que tu te demandes s’il faut les scinder. ## Ce qu’un skill embarque Un skill se téléverse comme un zip avec `SKILL.md` à la racine. Le frontmatter du fichier porte les métadonnées — description, licence, versions Python ou Node recommandées — et le corps porte les instructions. Les assets du bundle vivent sous `scripts/`, `references/` ou `assets/` : du code que l’agent peut exécuter quand il travaille dans une sandbox, et du matériel de référence qu’il lit à la demande. Un skill fait d’instructions pures est la bonne forme quand le comportement est une voix ou une contrainte — « cite toujours la source par numéro de section », « refuse les questions hors de ce produit ». Un skill avec scripts est la bonne forme quand le comportement est un calcul, une transformation ou une tâche en plusieurs étapes que le modèle devrait sinon improviser en tokens. ## Lier un skill à un agent Un skill devient visible pour un agent en le liant sur l’onglet **Skills** de l’agent — **Skills liés** liste la bibliothèque de l’organisation avec une case par skill. Un agent peut lier au plus dix skills, et un agent sans aucun lien n’en voit aucun : il n’y a pas de repli implicite vers une visibilité à l’échelle de l’organisation. L’agent lit un skill lié à l’exécution — la description lui dit quand le skill s’applique, et il tire alors le corps et les fichiers du bundle. Le lien est par agent : deux agents peuvent lier le même skill, et délier est symétrique — la requête suivante tourne sans lui. ## Gérer la bibliothèque Gérer les skills demande les permissions Admin ou Développeur. La bibliothèque vit dans les réglages Skills de l’organisation, où chaque skill montre son aperçu, le corps de ses instructions, l’arborescence de son bundle et une piste d’audit **Modifications récentes**. **Téléverser un skill** ajoute un nouveau bundle, **Remplacer le bundle** écrase l’existant en place, et **Dupliquer** le clone sous un nouveau slug. <Warning> Il n’y a pas d’épinglage de version : remplacer un bundle change ce que chaque agent lié lit dès la requête suivante, et supprimer un skill retire le bundle du disque — tout agent encore lié perd l’accès. </Warning> ## Quand y recourir | Utilise … quand | Skill | Instructions inline | | -------------------------------------------------------------------- | ----- | ------------------- | | Le motif se répète sur plusieurs agents | ✓ | | | Le comportement passe par des scripts que le modèle imiterait sinon | ✓ | | | Le comportement est la voix d’un seul agent | | ✓ | | Tu veux que l’organisation gouverne le comportement en un seul geste | ✓ | | | Les instructions de l’agent tiennent encore sur un écran | | ✓ | Les instructions inline sont la bonne forme pour un agent. Les skills sont la bonne forme quand le même comportement revient dans deux ou trois agents et que le coût de garder leurs instructions inline synchronisées commence à peser. ## Construis-en un Les skills sont le niveau d’abstraction au-dessus des quatre boutons — ils te laissent livrer un comportement une fois et laisser chaque agent qui en a besoin le récupérer en le liant. La marche suivante naturelle est [Construire un outil personnalisé](/fr/tutorials/developer/build-a-custom-tool) — elle va d’une page blanche à un skill avec scripts lié à un agent. # Agents externes Source: https://tale.dev/docs/fr/platform/agents/external-agent Tale fournit des **agents externes** intégrés — **Claude Code**, **Cursor**, **OpenCode**, **Hermes Agent**, **Gemini CLI**, **Codex**, **Pi** et **OpenClaw** — dont le tour entier s'exécute dans un bac à sable isolé. Au lieu de la boucle de chat habituelle, ton message est confié à cet agent de code, qui vit dans un conteneur neuf, modifie des fichiers, lance des commandes et rend compte. Tu lui parles directement dans le chat, et il conserve le même répertoire de travail et la même conversation d'un tour à l'autre, de sorte qu'une instruction de suivi comme « ajoute maintenant un test pour ça » reprend là où il s'était arrêté. C'est la même idée que de lancer un tel outil sur une machine distante, sauf que la machine est un bac à sable géré que l'espace de travail contrôle. Cette page explique comment les utiliser, ce que le bac à sable peut atteindre ou non, et comment ils sont facturés. ## Parler à un agent de code Choisis **Claude Code**, **Cursor**, **OpenCode**, **Hermes Agent**, **Gemini CLI**, **Codex**, **Pi** ou **OpenClaw** dans le sélecteur de chat et décris une tâche en langage clair — « écris un petit outil CLI en Python et teste-le », « clone ce dépôt et corrige le bug de l'issue #42 ». L'agent travaille dans son bac à sable : il planifie, écrit des fichiers, lance des commandes shell et installe des paquets au besoin, puis répond avec ce qu'il a fait. Pendant qu'il travaille, tu vois un indicateur de réflexion ; la réponse arrive quand le tour se termine. Inutile d'attendre la fin d'un tour. Le champ de saisie reste ouvert pendant que l'agent travaille : tout ce que tu envoies patiente dans la zone **Messages en attente** au-dessus du champ de saisie, puis est transmis à l'agent en cours à sa prochaine occasion. **Claude Code** les prend en plein tour, à la prochaine frontière d'outil — une correction comme « utilise pnpm, pas npm » arrive donc pendant que le travail se poursuit. **Cursor**, **OpenCode**, **Codex**, **Pi**, **OpenClaw** et les autres runtimes one-shot vident la file aux frontières de tour. Le message n'entre dans le fil qu'à ce moment-là, exactement à l'endroit où il a agi ; d'ici là tu peux le retirer (le × sur sa ligne). Appuyer sur **Stop** termine le tour en cours ; les messages encore en attente sont envoyés automatiquement quelques secondes plus tard comme tour suivant, avec le contexte de l'agent intact. Chaque fil de discussion est adossé à une session de bac à sable persistante. Les messages de suivi réutilisent la même session et les mêmes fichiers, et l'agent reprend son raisonnement antérieur au lieu de repartir de zéro. Comme la session appartient au fil, le fil garde aussi son agent : le sélecteur reste épinglé dessus, et changer d'agent ailleurs ne redirige jamais ce fil — ouvre une nouvelle discussion pour en utiliser un autre. Supprimer ou archiver le fil démonte le bac à sable et libère ses ressources. ## Ce que le bac à sable peut atteindre Le bac à sable démarre avec un répertoire de travail vide et est verrouillé par défaut. Les fichiers et dossiers que tu épingles avec `@` dans ton message sont livrés dans le bac à sable sous `/user/uploads/`, si bien que l'agent ouvre les vrais octets au lieu de travailler à partir d'un extrait de récupération. Le trafic réseau sortant est refusé sauf pour une petite liste d’autorisation (registres de paquets et GitHub), de sorte que l'agent peut installer des dépendances et cloner des dépôts publics mais ne peut pas atteindre des hôtes arbitraires. Par défaut, le modèle est atteint via la passerelle de l'espace de travail, jamais via une clé de fournisseur brute — le bac à sable ne détient qu'une clé éphémère et limitée par un budget pour ce tour. Ce comportement par défaut est le mode d'identifiants _géré_ de l'agent ; l'alternative _apporte tes propres identifiants_, traitée plus bas, place au contraire délibérément ta propre clé de fournisseur dans la boîte. Au-delà de ce verrouillage, l'agent peut atteindre n'importe quelle intégration que ton organisation a connectée — chercher sur le web via Tavily, appeler une API, interroger une base de données — tant que cette intégration est liée à l'agent. Tu les lies comme pour n'importe quel autre agent : ouvre l'onglet **Outils** de l'agent et sélectionne-les sous **Intégrations liées**. L'identifiant n'entre jamais dans le bac à sable ; quand l'agent appelle une intégration, la requête repart vers Tale, qui exécute l'appel avec l'identifiant stocké et ne renvoie que le résultat — un conteneur compromis ne peut donc pas lire tes clés. Une opération d'écriture ne s'exécute pas en silence : elle apparaît comme une carte d'approbation dans le chat et se déroule une fois que tu l'approuves. Les données de l'espace de travail lui-même empruntent le même chemin relayé. Sur ce même onglet **Outils**, tu peux aussi accorder des **outils de la plateforme** — recherche dans les connaissances, parcours et lecture de documents, enregistrement de fichiers dans le hub de documents — et l'agent les appelle depuis le bac à sable pendant qu'il travaille. Chaque appel s'exécute sur la plateforme dans le périmètre de connaissances de l'agent et ne renvoie que le résultat ; le bac à sable ne détient donc aucun identifiant de plateforme non plus, et un enregistrement dans le hub fait apparaître la même carte d'approbation que toute autre écriture. Les outils non liés ne peuvent pas être appelés, et un agent en mode « apporte tes propres identifiants », qui tourne sans clé de session, n'a pas de pont d'outils du tout. GitHub est l'exception qui place aussi un jeton dans le bac à sable, parce que `git` et la CLI `gh` en ont besoin localement : connecte GitHub sous [Intégrations](/fr/platform/integrations/overview) et lie-le à l'agent, et la session reçoit un jeton à portée limitée pour que l'agent puisse cloner, pousser et ouvrir des pull requests en ton nom. Tous les identifiants — le jeton GitHub dans le bac à sable comme ceux qui sont relayés — sont limités à la session, audités à chaque appel et révoqués à la fin de la session. ## Identifiants gérés et apportés par toi La façon dont l'agent atteint son modèle est un choix propre à chaque agent, défini dans l'onglet **Instructions** de l'agent, sous **Identifiants**. Trois backends d'identifiants existent ; l'interface les nomme selon le runtime de l'agent. **Géré par la passerelle (Claude Code, OpenCode, Hermes Agent, Gemini CLI, Codex, Pi et OpenClaw, géré)** est le mode par défaut pour ces runtimes. La plateforme forge une clé virtuelle éphémère pour le tour, achemine l'agent par sa passerelle, applique les modèles autorisés de l'agent depuis le catalogue **Fournisseurs**, mesure l'utilisation et applique les plafonds de dépense de l'organisation. Le bac à sable ne détient jamais de vraie clé de fournisseur. Les tours gérés de Hermes et de Codex passent par une route de passerelle compatible OpenAI (`OPENAI_BASE_URL` plus la clé virtuelle de session dans le bac à sable ; Codex y parle l'API Responses d'OpenAI) ; les tours Gemini CLI gérés par la route compatible Google GenAI de la passerelle (`GOOGLE_GEMINI_BASE_URL` plus la clé virtuelle de session comme `GEMINI_API_KEY`) ; les tours Pi gérés eux aussi par la route compatible OpenAI, câblée comme une configuration de fournisseur Pi propre au tour qui référence la clé virtuelle de session depuis l'environnement (le fichier de configuration ne contient jamais la clé) ; les tours OpenClaw gérés par la route compatible OpenAI de la passerelle, via une configuration de fournisseur générée à chaque tour. **Géré par l'environnement (Cursor, géré)** s'applique aux runtimes qui s'authentifient avec une clé API que tu stockes sur l'agent, pas via la passerelle. Ouvre la page **Environnement** de l'agent et définis `CURSOR_API_KEY` (ou la clé que le runtime déclare). Le modèle est un **identifiant runtime** que tu saisis dans la liste **Modèles** des Instructions — `composer-2.5`, par exemple — et non une entrée de catalogue. Ces tours ne sont **pas** mesurés dans l'Analyse d'utilisation ; la facturation relève de ton compte Cursor. **Apporte tes propres identifiants (BYO)** retire la plateforme du chemin de la requête pour les runtimes pris en charge (Claude Code, Cursor, Gemini CLI, Codex, Pi et OpenClaw). **OpenCode est géré uniquement** — sa configuration runtime pointe vers la passerelle de la plateforme et s'authentifie avec la clé virtuelle de session ; le BYO n'est pas disponible pour les agents OpenCode. Aucune clé virtuelle n'est forgée ; l'agent s'authentifie avec les identifiants que tu stockes sous [Variables d'environnement et secrets](/fr/platform/member/environment) et atteint directement le fournisseur. Le modèle devient un identifiant runtime brut que tu saisis tel quel plutôt qu'une entrée de catalogue. Comme la passerelle est contournée, la liste de modèles autorisés, les plafonds de dépense et la mesure d'utilisation de l'organisation ne s'appliquent pas aux tours BYO — la facturation et les limites passent à ton propre compte de fournisseur. Faire passer un agent du mode géré au mode BYO efface ses modèles de plateforme enregistrés lorsqu'il s'agissait de références de catalogue ; tu ressaisis les identifiants bruts. C'est aussi un déplacement de la frontière de confiance. En mode géré par la passerelle, le bac à sable ne détient qu'une clé de passerelle limitée par un budget ; en mode géré par l'environnement ou BYO, ton véritable identifiant de fournisseur est injecté dans l'environnement du bac à sable — la même posture que le jeton GitHub dans le bac à sable — de sorte que tout code que l'agent exécute dans la boîte peut le lire. C'est intentionnel : c'est ta boîte et ton identifiant. Configurer un agent est déjà une action privilégiée, si bien que le commutateur par agent est le seul contrôle ; il n'y a pas de bascule distincte au niveau de l'organisation. ## Moteurs et modèles **Claude Code**, **Cursor**, **OpenCode**, **Hermes Agent**, **Gemini CLI**, **Codex**, **Pi** et **OpenClaw** sont des entrées distinctes dans le sélecteur de chat (ou des agents que tu configures avec `agentKind` défini en conséquence). Pour **Claude Code, OpenCode, Hermes Agent, Gemini CLI, Codex, Pi ou OpenClaw géré par la passerelle**, le modèle provient de la liste des modèles pris en charge de l'agent dans le catalogue **Fournisseurs** — choisis-le dans le sélecteur de modèle. Claude Code et OpenCode sont livrés avec Claude Fable 5 par défaut, et la capacité de Fable est rationnée : une requête signalée par ses classificateurs de sécurité, un modèle surchargé ou un quota Fable épuisé ne fait pas échouer le tour — la session bascule automatiquement sur le modèle de repli défini dans l'entrée du catalogue, Claude Opus 4.8 (Claude Code uniquement ; OpenCode utilise l'identifiant de modèle de passerelle que tu as choisi). Hermes Agent, Pi et OpenClaw sont livrés avec Claude Sonnet 4.6 et Claude Opus 4.8, Gemini CLI avec Gemini 3 Pro et Gemini 3 Flash, Codex avec GPT-5.5 et GPT-5.5 Pro ; tous exécutent tout le tour sur le modèle choisi — sans repli automatique. Une particularité d'OpenClaw : son runtime rend compte en mode headless à la fin du tour, le chat affiche donc la réponse finale et l'utilisation, pas une chronologie outil par outil. Pour **Cursor géré par l'environnement** (et BYO sur tout runtime), l'éditeur **Modèles** des Instructions accepte des **identifiants runtime** de ton compte — exécute `agent models` dans une session de bac à sable pour voir ce que ton abonnement expose. Laisse la liste vide pour que le runtime choisisse son défaut (Auto). Le sélecteur de modèle du chat affiche un indicateur en lecture seule — le nom court de l'identifiant configuré, ou **Modèle par défaut** quand la liste est vide — plutôt que le menu déroulant du catalogue. Un agent **BYO Hermes Agent** utilise les identifiants que tu stockes sous [Variables d'environnement et secrets](/fr/platform/member/environment) — le plus souvent `OPENROUTER_API_KEY`, `OPENAI_API_KEY` ou `ANTHROPIC_API_KEY`, selon ton fournisseur. Définis le modèle sur un identifiant de style Hermes/OpenRouter (par exemple `openrouter:anthropic/claude-sonnet-4.6`). Un agent **BYO Gemini CLI** utilise tes propres identifiants Google stockés sous [Variables d'environnement et secrets](/fr/platform/member/environment) — `GEMINI_API_KEY` pour l'API Gemini, ou `GOOGLE_API_KEY` avec `GOOGLE_GENAI_USE_VERTEXAI=true` pour Vertex AI. Saisis des identifiants de modèle Google bruts (par exemple `gemini-3.1-pro-preview`) ; les valeurs par défaut livrées au format catalogue sont traduites à l'exécution en leurs identifiants natifs Google. Un agent **BYO Pi** utilise les identifiants que tu stockes sous [Variables d'environnement et secrets](/fr/platform/member/environment) — le plus souvent `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY` ou `OPENAI_API_KEY`, selon ton fournisseur. Définis le modèle sur un identifiant du propre catalogue de Pi (`pi --list-models` dans une session de bac à sable) — par exemple `anthropic/claude-sonnet-4.6` avec une clé OpenRouter ; les valeurs par défaut livrées au format catalogue sont traduites à l'exécution en ces identifiants de style OpenRouter. Pi n'a pas d'outils web intégrés ; les informations externes passent par les intégrations liées ou par ce que `curl` atteint sur la liste d'autorisation réseau du bac à sable. Un agent **BYO OpenClaw** utilise les identifiants que tu stockes sous [Variables d'environnement et secrets](/fr/platform/member/environment) — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` ou `OPENROUTER_API_KEY`, selon ton fournisseur. Définis le modèle sur une référence OpenClaw `provider/model` (par exemple `anthropic/claude-sonnet-4-6`), ou laisse-le vide pour le défaut du runtime. Un agent **BYO Codex** utilise l'`OPENAI_API_KEY` que tu stockes sous [Variables d'environnement et secrets](/fr/platform/member/environment) et parle directement à l'API d'OpenAI. Les références de catalogue livrées sont traduites via le `nativeModelId` de l'entrée (`gpt-5.5`, par exemple) ; les identifiants que tu saisis toi-même passent inchangés. Un agent **BYO Claude Code** saisit des identifiants Anthropic bruts — `claude-opus-4-20250514`, par exemple — par ordre de priorité. Les agents pack livrés qui portent encore des références de catalogue sont traduits à l'exécution via le `nativeModelId` de chaque entrée ; les identifiants que tu as saisis toi-même passent inchangés. ## Coût et budget Les tours d'agents externes peuvent être longs et appeler le modèle de nombreuses fois ; ils coûtent donc plus qu'une simple réponse de chat. Chaque tour géré s'exécute sur un budget par tour, et les [Politiques et limites](/fr/platform/admin/governance/policies-and-limits) de l'organisation plafonnent les dépenses par utilisateur, par équipe ou par agent. L'utilisation est mesurée dans l'[Analyse d'utilisation](/fr/platform/admin/governance/usage-analytics) au même titre que tout autre agent, attribuée à l'agent externe pour que tu voies ce que coûtent ces exécutions. Cette comptabilité est une propriété du chemin **géré par la passerelle** — elle couvre donc les tours gérés de Claude Code, OpenCode, Hermes Agent, Gemini CLI, Codex, Pi et OpenClaw. Les agents gérés par l'environnement et BYO s'exécutent sur des identifiants hors passerelle : leurs tours ne sont pas mesurés dans l'Analyse d'utilisation et les plafonds de dépense de l'organisation ne s'appliquent pas ; le coût et les éventuelles limites de débit relèvent de ton compte de fournisseur. ## Agents de code sur le board de tâches Dans les paramètres, **Agent de code** est le libellé produit pour les agents dont le chat tourne dans une CLI en bac à sable (Claude Code ou Cursor), ou dont le dispatch de tâches est configuré en JSON avec un **`runtime`** (tale-daemon sur ta machine) ou **`preferDurableStepForTasks`** (étape durable en bac à sable). Ce libellé ne change pas à lui seul l'exécution sur le board — le dispatch suit ces champs JSON, pas le bac à sable du chat. Quand tu assignes un agent de code à une tâche du board, le comportement dépend de la configuration : - **Agent** (boucle d'outils plateforme, sans CLI bac à sable, sans runtime de tâche) — utilise les outils plateforme et publie les résultats en commentaires de tâche. - **Agent de code + `runtime`** — les tâches s'exécutent sur ta machine (tale-daemon) dans un workspace git. - **Agent de code + `preferDurableStepForTasks`** — les tâches s'exécutent dans un conteneur bac à sable ; le résultat est un fichier de synthèse. - **Agent de code, bac à sable seul** (chat external-agent, sans runtime ni flag durable) — le chat tourne en bac à sable ; **les tâches du board passent par la boucle plateforme** tant que tu n'as pas lié un daemon ou activé les tâches durables dans le JSON de l'agent. Le sélecteur d'assigné affiche ces indications au choix. Pour la recherche, la rédaction ou des livrables personnels, assigne une personne ou un **Agent** plateforme plutôt qu'un agent de code orienté dépôt. ## Où cela s'inscrit Un agent externe transforme un fil de discussion en une session en direct avec un outil de code dans un bac à sable — tu le pilotes en langage clair, il travaille dans un espace de travail isolé, et la session persiste pour les suivis jusqu'à ce que tu fermes le fil. Les identifiants sont l'axe qui décide quelle part de tout cela s'exécute sous le contrôle de l'organisation : un agent géré par la passerelle reste sur la passerelle de la plateforme, sous les plafonds et la mesure de l'organisation, tandis qu'un agent géré par l'environnement ou BYO s'exécute sur les clés que tu conserves sous [Variables d'environnement et secrets](/fr/platform/member/environment) et répond à ton propre compte de fournisseur. Les candidats à la dérive ici sont les noms d'agent et de modèle ; associe cette page à la liste des [Fournisseurs](/fr/platform/admin/providers) en cours plutôt que de mémoriser des chaînes de modèle spécifiques, et à [Intégrations](/fr/platform/integrations/overview) pour les intégrations connectées que l'agent peut atteindre — de GitHub pour un véritable flux de pull request à une intégration de recherche ou de données qui amène des faits externes dans le travail. Pour exécuter Claude Code ou Codex sur du matériel que tu contrôles plutôt que dans le bac à sable géré — pour des tâches de board plutôt que du chat —, voir [tale-daemon](/fr/self-hosted/operate/tale-daemon). # Connaissances d’agent Source: https://tale.dev/docs/fr/platform/agents/knowledge Les connaissances sont ce qu’un agent peut récupérer et citer au moment de répondre. Sans elles l’agent est générique ; avec elles il répond depuis tes documents et cite d’où vient la réponse. L’onglet **Base de connaissances** de l’agent contrôle deux choses : _comment_ l’agent récupère (le mode de récupération) et _ce qui_ est dans la portée (quels documents). <Frame caption="L’onglet Base de connaissances — le mode de récupération au-dessus, les portées de documents et ce que chacune tient en dessous."> ![L’onglet Base de connaissances de l’éditeur d’agent avec Outil choisi parmi les quatre modes de récupération, les interrupteurs des documents d’équipe et d’organisation tous deux actifs, un encadré de documents d’équipe indiquant qu’aucun document n’a été trouvé pour cette équipe, et la liste des documents de l’organisation où chaque fichier porte un badge Indexé.](/images/platform/agent-editor-knowledge.webp) </Frame> ## Choisir un mode de récupération Quatre modes arbitrent entre coût et couverture. **Outil** laisse l’agent chercher à la demande — la récupération ne tourne que quand le modèle décide d’en avoir besoin. **Contexte** injecte les connaissances pertinentes dans chaque réponse, que le modèle l’aurait demandé ou non. **Les deux** les combine, et **Désactivé** coupe entièrement la base de connaissances pour cet agent. Commence avec **Outil** ; passe à **Contexte** quand tout le travail de l’agent est de répondre depuis les documents et que tu veux la récupération à chaque réponse. ## Cadrer les documents La base de connaissances interroge les documents téléversés dans ton organisation — la même bibliothèque que tu gères sous [Documents](/fr/platform/knowledge/documents). Deux interrupteurs fixent la portée : **Inclure les documents de l'équipe** couvre l’équipe assignée à l’agent, et **Inclure les documents de l'organisation** couvre les documents assignés à aucune équipe. L’onglet liste ce que chaque portée contient à l’instant, avec l’état d’indexation par document — seuls les documents marqués **Indexé** sont récupérables. ## Donner à l’agent ses propres documents Les **Documents de l'agent** sont des téléversements que seul cet agent peut atteindre — clique sur **Téléverser des documents** et les fichiers rejoignent la portée de récupération de cet agent sans entrer dans la bibliothèque partagée. Va vers eux quand la source appartient au travail de l’agent plutôt qu’à l’organisation : un playbook de tri, une FAQ propre à un produit. ## Comment la récupération atterrit dans la réponse Quand l’agent récupère, les citations s’attachent aux phrases qu’elles soutiennent — survoler montre la source, cliquer l’ouvre. Tout ce qui est récupérable concourt à la pertinence à chaque question, donc garde la portée serrée : une portée large rend la récupération plus bruyante, pas plus intelligente. ## Quand y recourir Les enregistrements structurés et les sources vivantes sont des outils, pas des connaissances — et les fichiers pour une seule conversation sont des pièces jointes. Les frontières : | Utilise… | Quand l’agent a besoin… | | -------------------------------------------------------- | ------------------------------------------------------------------ | | les connaissances (cet onglet) | De chercher et citer des documents téléversés à chaque chat | | [Outils](/fr/platform/agents/tools) | Des clients, produits, fournisseurs, sites web ou systèmes vivants | | [Pièces jointes](/fr/platform/chat/attachments) | D’un fichier qui ne compte que pour un seul chat | | [Agents de projet](/fr/platform/projects/project-agents) | De connaissances cantonnées à un seul Projet | ## Où ça se situe Les connaissances d’agent répondent à « cet agent doit répondre depuis ces documents ». La section [Connaissances](/fr/platform/knowledge/overview) au sens large est l’endroit où les sources vivent et s’indexent ; cet onglet câble un agent sur une portée d’entre elles. Pour la construction de bout en bout — téléverser, cadrer, demander, vérifier les citations — parcours [Agent avec connaissances](/fr/tutorials/editor/agent-with-knowledge). # Versions d’agent Source: https://tale.dev/docs/fr/platform/agents/versions Chaque enregistrement d’un agent crée un instantané. Le bouton **Historique** en haut à droite de l’éditeur d’agent ouvre ces instantanés du plus récent au plus ancien ; comparer montre ce qui a changé, et restaurer remplace l’état courant par une version passée. Il n’y a pas de distinction entre enregistrement manuel et automatique — chaque changement persisté est une version. La mécanique est petite mais porteuse. La plupart des équipes ajustent les instructions d’un agent chaque semaine ; sans l’historique, l’équipe ne ferait jamais confiance aux modifications. ## Passer un changement en revue Ouvre l’agent et clique sur **Historique**. La liste montre **Version actuelle** en haut et chaque **Version de l'instantané** antérieure en dessous, avec l’auteur et l’horodatage sur chaque ligne. Choisis un instantané et **Comparer les modifications** passe en revue les différences entre lui et la version actuelle — les champs modifiés se surlignent — avant que tu décides de restaurer. ## Restaurer une version Depuis un instantané, clique sur **Restaurer cette version**. L’état courant de l’agent est remplacé par l’instantané — un toast confirme **Agent restauré depuis l'historique** — et la restauration atterrit sur la frise comme sa propre entrée, donc les restaurations s’additionnent, elles ne détruisent rien. Les chats déjà en cours sur la version précédente y restent jusqu’à leur fin ; la version restaurée s’applique à partir du chat suivant. ## Ce qui est versionné Le versionnage couvre la configuration de l’agent : les instructions, la liste de modèles, la sélection d’outils, les réglages de connaissances, les amorces de conversation et les métadonnées. Il ne couvre pas les sources de connaissances sous-jacentes — remplacer un document depuis lequel l’agent récupère change ce que l’agent répond sans incrémenter la version de l’agent. Pour auditer un changement de connaissances, voir [Journaux d’audit](/fr/platform/admin/governance/audit-logs). ## Où ça se situe Les versions sont le filet de sécurité de l’agent pour la même raison que git est celui du code : tout ce qui est enregistré est récupérable. La page à lire en regard est [Journaux d’audit](/fr/platform/admin/governance/audit-logs) — elle couvre la piste qui-a-fait-quoi à l’échelle de l’organisation ; l’Historique couvre la piste qu’était-ce, agent par agent. # Workers d'agent Source: https://tale.dev/docs/fr/platform/agents/delegation Tu lances un worker quand une tâche mérite son propre contexte ciblé : recherche ouverte, extraction en masse, rédaction d'un long document. L'agent avec qui tu discutes compose un **worker** à la demande — un nom, des instructions de tâche, une méthode de travail optionnelle et une sélection d'outils — le fait tourner et replie le résultat dans sa réponse. Les workers sont éphémères : ils existent pour un seul job, et leur exécution apparaît comme une **carte de job** dans le chat. Cette page te donne le modèle mental pour savoir quand un worker est la bonne forme et comment la plateforme le maintient borné. Le parcours de bout en bout vit dans [Confier du travail à un worker](/fr/tutorials/editor/delegate-between-agents). ## Comment tourne un job Quand l'agent appelle **spawn_agent**, Tale résout les capacités du worker, démarre une conversation enfant fraîche et fait tourner le worker en mode non interactif : il ne voit que la tâche envoyée par l'agent (pas tout l'historique du chat), suit sa progression sur une checklist visible en direct, et son dernier message revient à l'agent comme résultat. Le chat affiche une carte de job avec le nom du worker, la progression en direct, le statut final et une transcription dépliable de tout ce qu'il a fait. Les workers ne te parlent jamais. Si un worker a besoin d'une information que seul un humain peut donner, il le dit dans son résultat et l'agent te pose la question — les questions viennent toujours de l'agent avec qui tu parles réellement. ## Les capacités sont toujours un sous-ensemble Un worker ne peut détenir au plus que ce que détient l'agent qui le lance. Trois couches décident de la sélection effective : - **La configuration de l'org** — les outils, skills et intégrations de l'agent, tels que configurés par tes admins. Rien à gérer par worker. - **La sélection par job** — l'agent choisit le plus petit ensemble dans ses propres capacités pour cette tâche (moins d'outils = un worker plus ciblé). - **Les exceptions de plateforme** — quelques outils ne se transmettent jamais, au premier rang l'outil de question à l'utilisateur : les questions d'un worker passent par l'agent, pour qu'une réponse ne parte jamais dans le vide. Les workers ne peuvent pas non plus lancer de workers. Une exception va dans l'autre sens : chaque worker peut toujours lister et lire les fichiers du thread (téléversements, sorties générées) — écrire des fichiers ou exécuter du code reste une sélection explicite. Tout ce qui sort de ces bornes est silencieusement ignoré et signalé — la carte de job montre ce qui a été retranché, et l'agent s'adapte (en te disant par exemple qu'une intégration doit être connectée). ## Méthodes de travail Pour du travail ouvert, l'agent peut accorder un **skill de méthodologie** comme méthode de travail du worker — `web-research` est fourni : planification en direct sur la checklist, budgets de recherche par question et un livrable cité. Les méthodologies sont des skills ; tes admins les gouvernent comme n'importe quel autre skill. ## Délais et budget Un worker tourne dans le budget de tour restant de son agent et ne peut pas l'étendre ; si le temps manque, le job se termine en `temps écoulé`, avec sa progression partielle visible sur la carte. La consommation de tokens remonte à l'agent qui a lancé le job — les budgets mensuels par agent et les règles de budget de l'org voient la dépense du job comme celle de l'agent. Les admins plafonnent les jobs parallèles par organisation via **Gouvernance → agent_jobs** (10 par défaut). ## Quand y recourir | Prends … quand | Worker | Agent seul | Workflow | | -------------------------------------------------------- | ------ | ---------- | -------- | | Une sous-tâche profite d'un contexte isolé et ciblé | ✓ | | | | L'agent peut bien répondre directement | | ✓ | | | Le travail a des étapes fixes avec des validations entre | | | ✓ | Le coût d'un worker est une exécution de plus ; le gain, un contexte propre avec exactement les bonnes capacités pour la sous-tâche — et une carte de job qui montre ce qui s'est passé. Quand les étapes sont fixes et que tu veux des validations ou de la planification entre elles, un workflow est la bonne forme. # Outils d’agent Source: https://tale.dev/docs/fr/platform/agents/tools Les outils sont ce qu’un agent peut faire au-delà de produire du texte. Le modèle choisit quel outil appeler dans la liste que l’auteur de l’agent a accordée ; Tale exécute l’outil, rend le résultat, et le modèle continue. L’onglet **Outils** de l’agent est cette liste — un catalogue interrogeable d’interrupteurs par outil, groupés en cartes de catégorie. <Frame caption="Le catalogue d’outils — une carte par catégorie, chacune comptant combien de ses outils l’agent a reçus."> ![L’onglet Outils de l’éditeur d’agent, défilé jusqu’aux cartes de catégorie, avec Connaissances à trois outils cochés sur quatre et Fichiers à sept sur sept, tandis que Conversations, Discussions, Analytique et Tâches et projets n’ont rien d’accordé.](/images/platform/agent-editor-tools.webp) </Frame> ## Accorder les outils un par un Coche un outil et l’agent peut l’appeler dès la prochaine requête ; décoche-le et l’agent oublie qu’il existe. **Rechercher des outils…** filtre le catalogue par nom ou par catégorie, chaque ligne d’outil porte une description d’une ligne de ce qu’elle accorde, et la case d’en-tête d’une catégorie active tout le groupe d’un coup — le compteur à côté montre combien d’outils du groupe sont actifs. Les catégories reflètent les surfaces de la plateforme : **Clients**, **Produits**, **Fournisseurs** et **Sites web** exposent des outils de lecture et de mise à jour sur des enregistrements structurés ; **Conversations** et **Discussions** laissent l’agent lire et répondre ; **Connaissances** couvre la recherche et l’écriture de documents ; **Tâches et projets** inclut la propre liste de tâches de l’agent ; **Workflows** lui permet de créer et lancer des workflows ; **Fichiers** couvre les opérations de l’agent sur les fichiers ; **Système** contient **Exécuter du code**, **Demander à un humain** et les autres outils d’exécution. Accorde le plus petit ensemble qui fait le travail — chaque outil activé élargit ce que l’agent peut lire ou changer en ton nom. **Exécuter du code**, dans le groupe **Système**, est le plus large de ces outils : il exécute du Python, du Node ou du bash dans la sandbox propre au chat, et travaille sur les fichiers que le chat tient déjà plutôt que dans une boîte vide. Un appel lance un extrait de code directement, lance un script que l’agent a déposé sous `/user/code/`, ou installe seulement des paquets — les paquets déclarés s’installent d’abord et persistent le reste du tour, et ce que l’exécution écrit sous `/user/output/` réapparaît comme fichier dans le chat. Les fichiers et dossiers que tu épingles avec `@` arrivent dans cette sandbox sous `/user/uploads/`, si bien que le code ouvre les vrais octets plutôt qu’un extrait de récupération. <Note> Un agent lance de lui-même un **worker** ciblé pour une sous-tâche — ce n’est pas un outil que tu actives ici. [Workers d’agent](/fr/platform/agents/delegation) couvre quand c’est le bon mouvement et comment un worker hérite d’un sous-ensemble borné des capacités de l’agent. </Note> ## Configurer la recherche web **Recherche web** en haut de l’onglet est un mode, pas une case : **Désactivé**, **Outil** (l’agent cherche à la demande), **Contexte** (les résultats web pertinents sont injectés dans chaque réponse) ou **Les deux**. La recherche web ne parcourt que le contenu des sites web ajoutés à ton organisation — ce n’est pas un crawl ouvert ; gère les sources sous [Sites web](/fr/platform/knowledge/crawling). ## Lier des intégrations et des workflows Sous le catalogue, **Intégrations liées** et **Flux de travail liés** attachent des intégrations ou des workflows précis comme outils dédiés, pour que l’agent les appelle sans nommer lui-même l’intégration ou l’identifiant du workflow. Lie ceux dont le travail de l’agent dépend ; les [serveurs MCP](/fr/platform/integrations/mcp-servers) connectés atteignent l’agent par le même chemin, à travers les intégrations de l’organisation. ## Comment les appels d’outil s’affichent Les appels d’outil apparaissent dans le chat comme des cartes repliées entre le message de l’utilisateur et la réponse. Déplier une carte révèle le nom de l’outil, les entrées émises par le modèle et le résultat rendu par Tale. Un appel d’outil échoué montre l’erreur ; le modèle réessaie en général avec une autre forme au tour suivant. ## Quand y recourir | Utilise les outils quand… | Utilise les connaissances quand… | | ----------------------------------------------------------------------- | -------------------------------------------------- | | L’agent doit agir — interroger, mettre à jour, exécuter, répondre | L’agent doit citer les documents qu’il a récupérés | | Les données sont des enregistrements structurés ou des systèmes vivants | Les données sont du contenu téléversé ou crawlé | ## Où ça se situe Les outils élargissent ce qu’un agent peut faire ; ils élargissent aussi la frontière de confiance, puisque l’agent peut désormais lire, écrire ou appeler des choses au nom de l’utilisateur. Couple cette page avec la [politique run-code](/fr/platform/admin/governance/run-code-policy) si l’agent exécutera du code. Les instructions de l’agent restent l’endroit où vit la **politique** ; l’onglet **Outils** est l’endroit où vit la **surface**. # Bibliothèque de prompts Source: https://tale.dev/docs/fr/platform/workspace/prompt-library La bibliothèque de prompts est la surface des prompts enregistrés de Tale. C’est là que tu gardes les amorces de chat que tu cherches plus d’une fois — un prompt de voix d’écriture que tu réutilises pour chaque brouillon de mail client, un prompt de débogage que ton équipe se passe, un prompt de recherche sur lequel toute l’org devrait s’aligner. Chaque rôle au-dessus de Désactivé peut enregistrer et utiliser des prompts ; le levier **visibilité** sur chaque prompt décide qui d’autre le voit. Cette page est la référence pour ce qu’est un prompt, comment se comportent les trois niveaux de visibilité, comment marche l’historique des versions, et comment les prompts entrent dans un chat. La bibliothèque vit sous **Prompts** dans la barre latérale ; la même bibliothèque apparaît en ligne dans le composeur de chat. <Frame caption="La bibliothèque de prompts par-dessus le composeur de chat — les amorces provisionnées avec les onglets de portée et les filtres qui rétrécissent la liste."> ![La boîte de dialogue de la bibliothèque de prompts ouverte par-dessus le composeur de chat, listant les amorces provisionnées avec des onglets de portée et une ligne de filtres au-dessus.](/images/platform/prompt-library-dialog.webp) </Frame> ## Ce qu’est un prompt Un prompt est un morceau de texte enregistré — généralement une question ou une instruction que tu taperais autrement dans le composeur — avec un titre et quelques champs de métadonnées. Quand tu vas chercher un prompt enregistré dans chat, Tale colle son contenu dans le composeur ; tu peux éditer avant d’envoyer, le prompt n’est pas un message système caché. Chaque prompt porte : - Un **titre** (utilisé dans le picker ; auto-généré du contenu si tu le laisses vide). - Le **contenu** (le texte du prompt lui-même). - Une **visibilité** — `Personnel`, `Équipe`, ou `Global`. - Une liaison **équipe** optionnelle (quand visibilité est `Équipe`). - Des **tags** optionnels pour filtrer. La bibliothèque est cherchable par titre et contenu, filtrable par visibilité et tag, et triable par récence. Le picker en ligne du composeur est la même bibliothèque avec les mêmes filtres. ## Les trois niveaux de visibilité **Personnel** est pour tes yeux uniquement. Un prompt personnel apparaît dans ta propre bibliothèque et nulle part ailleurs ; personne dans l’org ne peut le voir. Va vers personnel quand le prompt est formé à ton propre flux et que le reste de l’équipe n’en tirerait pas profit. **Équipe** est partagé avec une équipe. Choisis l’équipe à l’enregistrement ; chaque membre de cette équipe voit le prompt dans sa bibliothèque. Va vers équipe quand le prompt est formé à une fonction spécifique — le prompt de ton-de-réponse de l’équipe support, le prompt de triage-bugs de l’équipe ingénierie — et que le reste de l’org n’en tirerait pas profit. **Global** est à l’échelle de l’org. Chaque membre de l’org voit le prompt dans sa bibliothèque. Va vers global quand le prompt encode une décision que toute l’org devrait prendre de la même façon — la voix d’écriture qu’attend la marque, le modèle de question avec lequel chaque chercheur devrait commencer. La visibilité se règle à l’enregistrement et s’édite plus tard. Promouvoir un prompt personnel à global est un clic et ne déclenche aucune migration sur les chats qui l’avaient déjà utilisé — les anciens chats gardent leur contenu collé, la nouvelle visibilité n’affecte que l’entrée de bibliothèque. ## Versionnement Enregistrer un prompt par-dessus une entrée existante crée une nouvelle version. L’historique des versions est joignable depuis la ligne du prompt ; chaque version enregistre l’éditeur, l’horodatage, et le diff de contenu. Tu peux revenir à n’importe quelle version antérieure en un clic. L’historique des versions est l’endroit où regarder quand un coéquipier a édité un prompt global et que le nouveau contenu ne marche pas pour ton cas d’usage. Reviens en arrière au niveau bibliothèque si tout le monde devrait revenir ; copie la version plus ancienne dans un prompt personnel si seul toi veux l’ancien comportement. ## Utiliser un prompt dans chat Le composeur de chat a un picker de prompts à sa base. Ouvre-le, cherche ou filtre pour trouver le prompt voulu, et clique-le pour coller le contenu dans le composeur. Le prompt est maintenant ton message — édite-le, attache des fichiers, ajoute du contexte, envoie. Une fois envoyé, le prompt agit comme n’importe quelle entrée de composeur ; Tale ne suit pas quels chats ont utilisé quels prompts. Certains prompts contiennent des variables de template — placeholders comme `{{customer_name}}` ou `{{topic}}`. Le picker te demande chaque variable avant de coller ; le contenu résultant est le prompt avec les placeholders remplis. Les variables sont déclarées dans le contenu du prompt avec la syntaxe `{{variable_name}}`. ## Limites et cycle de vie Le contenu d’un prompt a une limite de taille — le formulaire de bibliothèque montre l’usage actuel contre le maximum, et le bouton Enregistrer est désactivé si tu dépasses. La limite est généreuse assez pour que la plupart des prompts passent ; si tu butes, la bonne réponse est généralement que le prompt est deux prompts. Supprimer un prompt n’est réversible que via l’historique des versions si tu l’avais enregistré au moins une fois avant. Les prompts personnels sont supprimés définitivement à la suppression de compte ; les prompts d’équipe survivent à la réorganisation d’équipe sauf si l’équipe est supprimée ; les prompts globaux survivent à tout sauf à une suppression explicite. ## Où cela s’inscrit La bibliothèque de prompts est la forme la plus légère de réutilisation dans Tale — plus légère qu’un agent (qui porte instructions, connaissance et tools), plus légère qu’un skill (qui empaquette instructions et un script). Va vers un prompt quand la réutilisation est juste le texte ; va vers un agent quand la réutilisation est un comportement configuré. La lecture suivante naturelle est [Amorces et prompts](/fr/platform/chat/starters-and-prompts) pour comment les prompts surgissent dans le composeur de chat à côté des amorces propres d’un agent. # Base de connaissances Source: https://tale.dev/docs/fr/platform/knowledge/overview La base de connaissances est l’espace où vivent les données de l’organisation pour que les agents puissent les lire et les citer. Les éditeurs la constituent une fois ; les agents y puisent au moment de répondre — c’est ce qui permet à un agent Tale de répondre avec ta réalité plutôt qu’avec les données d’entraînement du modèle. L’espace s’ouvre sur six onglets : **Documents**, **Entrées de connaissances**, **Sites web**, **Produits**, **Clients** et **Fournisseurs**. <Frame caption="L’onglet Documents — le coin le plus utilisé de la base de connaissances."> ![L’onglet Documents de la base de connaissances listant trois fichiers texte téléversés avec les colonnes taille, source, statut RAG et équipes.](/images/get-started/documents-list.webp) </Frame> ## Les deux formes Tout ce que contient l’espace prend l’une de deux formes. Le **contenu indexé** — les fichiers de Documents, les faits des Entrées de connaissances, les pages qu’une exploration de site web ramène — passe par le pipeline d’indexation (extraction, découpage, embeddings, stockage) pour que les agents récupèrent les passages pertinents et les citent. Les **fiches typées** — Produits, Clients, Fournisseurs — sont des lignes à champs nommés que les agents lisent comme des données, pas comme de la prose : des valeurs exactes, sans approximation de récupération. La forme que tu choisis décide de la façon dont un agent peut exploiter le contenu — c’est pourquoi [Données structurées](/fr/platform/knowledge/structured-data) est une page de décision, pas seulement une référence. ## Comment les agents y puisent Un agent ne voit pas toute la bibliothèque par défaut. L’onglet **Base de connaissances** de l’agent contrôle son périmètre de récupération — les parties de la bibliothèque qu’il interroge au moment de répondre — et les éléments limités à une équipe restent invisibles pour les agents et les membres hors de cette équipe. La récupération passe par les outils RAG de l’agent, et chaque passage récupéré porte sa source : les citations renvoient au fichier, à l’entrée ou à la page d’origine. La mécanique côté agent vit dans [Connaissances de l’agent](/fr/platform/agents/knowledge). ## Pages dans cette section <CardGroup cols="2"> <Card title="Documents" icon="file-text" href="/fr/platform/knowledge/documents"> Téléverser des fichiers, le pipeline d’indexation, les formats pris en charge et le cycle de vie de chaque document. </Card> <Card title="Entrées de connaissances" icon="book-open" href="/fr/platform/knowledge/knowledge-entries"> De petits faits indexés par sujet — capturés depuis le chat avec approbation ou ajoutés à la main. </Card> <Card title="Exploration de sites web" icon="globe" href="/fr/platform/knowledge/crawling"> Transformer un site public en connaissances — domaine, intervalle d’analyse et vue des pages indexées. </Card> <Card title="Données structurées" icon="table" href="/fr/platform/knowledge/structured-data"> Clients, Produits, Fournisseurs, Sites web — quand une fiche typée bat un document. </Card> </CardGroup> ## Où cela s’inscrit La base de connaissances est la couche de données sur laquelle repose chaque réponse ancrée ; sans elle, les agents ne savent que ce que le modèle sait déjà. Fais entrer le contenu par l’onglet qui correspond à sa forme, puis branche les agents dessus — la suite naturelle est [Documents](/fr/platform/knowledge/documents) pour les fichiers, [Données structurées](/fr/platform/knowledge/structured-data) pour les fiches et [Connaissances de l’agent](/fr/platform/agents/knowledge) pour le volet récupération. # Documents Source: https://tale.dev/docs/fr/platform/knowledge/documents L’onglet Documents est la surface fichiers de la base de connaissances. Les éditeurs téléversent des fichiers, Tale fait passer chacun par le pipeline d’indexation — extraire le texte, le découper, calculer les embeddings, les stocker — et les agents dont le périmètre de connaissances couvre le document récupèrent les passages pertinents au moment de répondre et les citent. Cette page couvre le côté opérateur : le téléversement, la colonne de statut, la portée par équipe, les dossiers et le cycle de vie d’un document. <Frame caption="La table des documents — taille, source, statut RAG et portée d’équipe par fichier."> ![L’onglet Documents de la base de connaissances listant trois fichiers texte téléversés avec les colonnes taille, source, statut RAG et équipes.](/images/get-started/documents-list.webp) </Frame> ## Téléverser Ouvre **Connaissances > Documents** et clique sur **Téléverser des documents** — le menu propose **Depuis ton appareil** et **Depuis Microsoft 365**. Le portail de téléversement accepte les formats qui couvrent l’essentiel des connaissances d’une organisation : PDF, Word (`.doc`, `.docx`), texte OpenDocument (`.odt`), PowerPoint (`.ppt`, `.pptx`), Excel (`.xls`, `.xlsx`), CSV, texte brut et images (JPG, PNG, GIF, WEBP). Tout le reste est refusé dès le téléversement. Téléverser et indexer sont deux faits distincts, et la colonne **Statut RAG** suit le second : **Indexation** pendant que le pipeline tourne, **Indexé** quand les agents peuvent récupérer le contenu, **Échoué** quand le pipeline a rencontré une erreur, et **Réindexation nécessaire** quand les fragments stockés sont périmés. Les formats modernes s’indexent ; le trio Office historique (`.doc`, `.xls`, `.ppt`) se téléverse et reste téléchargeable mais affiche **Non indexé** — les agents ne peuvent pas récupérer son contenu tant que tu ne l’as pas réenregistré au format moderne. ## Importer depuis Microsoft 365 **Depuis Microsoft 365** importe depuis OneDrive ou SharePoint au lieu du disque : choisis des fichiers ou des dossiers, puis le mode d’importation. **Importation unique** apporte les fichiers une fois — ils se comportent comme des téléversements depuis le disque. **Importation synchronisée** garde la sélection synchronisée : les nouveaux fichiers du dossier OneDrive apparaissent lors d’un passage de sync ultérieur, les fichiers modifiés sont réindexés, et les fichiers supprimés à la source quittent l’espace de travail. Les deux modes préservent la structure de dossiers de ta sélection. La synchronisation couvre les dossiers OneDrive personnels — une sélection SharePoint s’importe toujours une seule fois. Pour arrêter la synchronisation — d’un dossier synchronisé entier ou d’un seul fichier synchronisé — ouvre le menu de la ligne et clique sur **Arrêter la synchronisation** ; les documents importés restent dans l’espace de travail et cessent d’être mis à jour. Supprimer un dossier ou un fichier synchronisé arrête aussi sa synchronisation. Dans tous les cas, les fichiers dans OneDrive restent intacts. ## Portée, dossiers, sources Chaque ligne porte une cellule **Équipes** — **Toute l'organisation** par défaut, ou les équipes que tu choisis via **Assigner une équipe** dans le menu de la ligne. Un document limité à une équipe est invisible pour les membres et les agents hors de cette équipe ; c’est le levier d’accès de la base de connaissances. Les fichiers de projet sont entièrement hors de ce modèle : l’onglet **Connaissances** d’un projet contient des fichiers scopés à ce seul projet, et ils n’apparaissent ni dans cette bibliothèque ni dans sa portée par équipe — voir [Gérer les fichiers](/fr/platform/projects/manage-files). **Nouveau dossier** garde les grandes bibliothèques navigables, et les intégrations apportent leur propre structure : les documents synchronisés depuis OneDrive ou SharePoint atterrissent dans des dossiers de synchronisation et affichent leur origine dans la colonne **Source**, ce qui garde les citations traçables jusqu’au système amont. <Warning> Supprimer un dossier supprime définitivement chaque fichier et sous-dossier qu’il contient. Supprimer un dossier de synchronisation OneDrive retire aussi sa configuration de synchronisation automatique et son historique — mais jamais les fichiers dans OneDrive lui-même. </Warning> ## Réindexer et supprimer **Réindexer** (menu de la ligne) refait passer le pipeline sur le fichier stocké — le bon geste après un échec d’indexation ou quand un document affiche **Réindexation nécessaire**. **Supprimer** retire le document et ses fragments indexés ; la confirmation le dit sans détour — l’action est irréversible. Retéléverser le même fichier ramène le contenu sous la forme d’un nouveau document. Cliquer sur un document ouvre l’aperçu, avec un panneau latéral qui montre la taille, la source, le statut RAG, les équipes, l’auteur du téléversement et la date de modification — le moyen le plus rapide de vérifier ce que vise réellement une citation. ## Documents ou données structurées Les documents sont la moitié non structurée de la base de connaissances. Quand le contenu est une liste d’éléments partageant les mêmes champs — clients, produits, fournisseurs — une fiche typée sert mieux les agents qu’un tableur téléversé : des valeurs exactes au lieu de passages récupérés. Les règles de décision vivent dans [Données structurées](/fr/platform/knowledge/structured-data). ## Où cela s’inscrit Les documents sont le coin le plus utilisé de la base de connaissances — la plupart des citations, dans la plupart des réponses, pointent ici. Le volet récupération — comment le périmètre de connaissances d’un agent décide de ce qu’il interroge — est [Connaissances de l’agent](/fr/platform/agents/knowledge) ; la surface sœur au format fait est [Entrées de connaissances](/fr/platform/knowledge/knowledge-entries), qui emprunte le même pipeline un document à la fois. # Exploration de sites web Source: https://tale.dev/docs/fr/platform/knowledge/crawling Un site web est la forme que prend, dans la base de connaissances, « un site public que l’agent doit connaître ». Tu confies à Tale un domaine et un intervalle d’analyse ; le crawler découvre les URL, va chercher les pages, extrait le contenu principal, découpe le texte et calcule ses embeddings, puis sert les fragments au moment de répondre, exactement comme pour les Documents. Cette page parcourt ce que tu vois entre l’ajout d’un domaine et les citations de ses pages par les agents. <Frame caption="Ajouter un site web — un domaine plus un intervalle d’analyse, et le formulaire est complet."> ![La boîte de dialogue Ajouter un site web de l’onglet Sites web, demandant un domaine et un intervalle d’analyse réglé par défaut sur toutes les 6 heures.](/images/platform/websites-add-dialog.webp) </Frame> ## Ajouter un site web Ouvre **Connaissances > Sites web** et clique sur **Ajouter un site web**. La boîte de dialogue a deux champs : **Domaine** (par exemple `example.com`) et **Intervalle d'analyse** — toutes les heures, toutes les 6 heures (le réglage par défaut), toutes les 12 heures, tous les jours, tous les 5, 7 ou 30 jours. Tale normalise le domaine — `https://`, `www.` et les barres obliques finales sont tolérés — et rejette tout ce qui ne se lit pas comme un nom d’hôte. Clique sur **Enregistrer** ; le planificateur ramasse les nouveaux sites à son prochain passage, la première analyse démarre donc en quelques secondes. <Note> Il n’y a ni champ d’authentification ni liste de chemins à inclure ou exclure — le crawler voit exactement ce qu’un visiteur anonyme voit. Tout ce qui vit derrière une connexion relève de [Documents](/fr/platform/knowledge/documents) ou d’une [intégration](/fr/platform/integrations/overview). </Note> ## Comment les URL sont découvertes Le crawler tente d’abord la voie coopérative. Il résout la page d’accueil et parcourt chaque sitemap que le site publie — `sitemap.xml`, index de sitemaps, sitemaps compressés ou déclarés dans le robots.txt — pour collecter la liste d’URL que le site entretient lui-même. Les sites au sitemap sain obtiennent une couverture complète, sans rien deviner. Quand le sitemap manque, est cassé ou vide, le crawler se rabat sur un parcours de liens en largeur depuis la page d’accueil : liens du domaine uniquement, liens externes et sociaux écartés, navigation et pied de page retirés avant l’extraction. Ce repli couvre les sites sans sitemap, mais il ne peut pas égaler la complétude d’un sitemap bien tenu. ## Le planning d’analyse L’intervalle décide de la fréquence à laquelle les URL sont redécouvertes et les pages rechargées. Chaque analyse est incrémentale : les pages inchangées sont sautées, les pages modifiées sont réextraites et réindexées, les nouvelles pages sont ajoutées, les pages disparues sont retirées de l’index. Les agents pointés sur le site voient le nouveau contenu dès la récupération suivante — il n’y a pas d’étape de publication séparée. ## Lire la table Chaque ligne montre le domaine, son **Statut** — **Inactif** entre deux analyses, **En cours d'analyse** en vol, **Actif** après une analyse réussie, **Erreur** quand la dernière analyse a échoué, **Suppression en cours** pendant le retrait — le pourcentage **Indexé** (survole-le pour le compte de pages explorées sur le total), l’heure de dernière analyse dans **Analysé** et l’**Intervalle**. Ouvre une ligne pour le titre et la description découverts du site ; clique sur **Voir les pages** pour la liste des pages — chaque URL indexée avec son nombre de mots, son nombre de fragments et sa dernière exploration, plus un champ de recherche qui interroge les fragments indexés : le moyen le plus rapide de vérifier ce qu’un agent récupérerait réellement. ## Où cela s’inscrit L’exploration est le moyen économique d’amener un site public dans le contexte des agents : un domaine, une cadence, et le reste est l’affaire du crawler. La contrepartie est la frontière du visiteur anonyme — le contenu privé passe par [Documents](/fr/platform/knowledge/documents) ou une intégration. Pour la place des lignes Sites web à côté des Clients, Produits et Fournisseurs, lis [Données structurées](/fr/platform/knowledge/structured-data). # Entrées de connaissances Source: https://tale.dev/docs/fr/platform/knowledge/knowledge-entries Les entrées de connaissances sont la surface « faits » de la base de connaissances. Là où un document transporte un fichier entier, une entrée porte un seul fait, petit et durable — « le magasin ouvre à 9 h », « le délai de retour est de 3 jours » — indexé par un nom de sujet. Les entrées empruntent le même pipeline d’indexation que les documents, si bien que chaque agent dont le périmètre les couvre les récupère et les cite comme n’importe quelle source ; ce qui les rend particulières, c’est la façon dont elles entrent et dont les corrections remplacent ce qu’elles corrigent. <Frame caption="L’onglet Entrées de connaissances — sujet, contenu, source et statut d’indexation par fait."> ![L’onglet Entrées de connaissances listant trois faits ajoutés à la main, chacun avec l’étiquette de source Manuel et le badge de statut Indexé.](/images/platform/knowledge-entries-list.webp) </Frame> ## D’où viennent les entrées **Depuis le chat, avec ton approbation.** Les agents dont l’outil d’écriture dans les connaissances est activé peuvent proposer d’enregistrer un fait que tu as énoncé ou corrigé pendant un chat. La proposition apparaît comme une carte dans le chat — **Enregistrer dans la base de connaissances**, avec le sujet et le contenu complet ; quand le sujet existe déjà, la carte devient **Mettre à jour la base de connaissances** et prévient que l’approbation remplacera l’entrée existante. Rien n’atterrit tant que tu n’as pas cliqué sur **Approuver** ; **Rejeter** écarte la proposition. <Note> L’outil est désactivé par défaut — active-le agent par agent dans les réglages d’outils de l’agent. Un agent ne peut jamais écrire dans les connaissances partagées de l’organisation sans qu’un humain valide le texte exact. </Note> **À la main.** Clique sur **Ajouter une entrée** dans **Connaissances > Entrées de connaissances**. Donne-lui un **Sujet** (120 caractères au maximum — court et stable, comme un titre) et le **Contenu** en markdown (8 000 caractères au maximum), rédigé pour rester compréhensible sans la conversation autour. La colonne **Source** distingue les deux origines : **Chat** ou **Manuel**. ## Une seule version active par sujet Le sujet est la clé de déduplication : une proposition de chat approuvée pour un sujet existant, ou une modification, remplace la version active au lieu d’en ajouter une seconde — la base de connaissances ne sert jamais deux versions du même fait. Ajouter une nouvelle entrée sous un sujet existant est refusé avec une erreur de sujet en double ; modifie l’entrée existante à la place. Les versions remplacées ne sont pas perdues. Ouvre une entrée pour voir ses détails — le statut d’indexation, la dernière mise à jour et l’**Historique des versions**, avec chaque version remplacée et la date de son remplacement. Seule la version active est indexée pour la récupération ; l’historique existe pour l’audit et la référence. ## Modifier, indexer, supprimer Modifier crée une nouvelle version active et réindexe en arrière-plan — le badge de statut repasse par l’indexation et revient à **Indexé** quand la recherche reprend le nouveau texte. Supprimer retire l’entrée entière : la confirmation prévient qu’elle disparaît aussi de la base de connaissances, que les agents ne pourront plus la trouver, et que l’action est irréversible. Si le fait était juste, ajoute-le de nouveau. ## Où cela s’inscrit Les entrées de connaissances bouclent la boucle entre les conversations et la base de connaissances : une correction faite une fois dans le chat devient un fait que chaque agent récupère, avec un humain qui approuve la formulation exacte, et une seule version active par sujet qui garantit que l’ancien fait disparaît quand le nouveau atterrit. Pour la moitié au format fichier, lis [Documents](/fr/platform/knowledge/documents) ; pour la façon dont les agents s’y relient et récupèrent, lis [Connaissances de l’agent](/fr/platform/agents/knowledge). # Données structurées Source: https://tale.dev/docs/fr/platform/knowledge/structured-data La base de connaissances de Tale embarque deux formes côte à côte. Les documents sont du texte dont l’agent récupère des fragments ; les fiches structurées sont des lignes typées dont l’agent lit les champs. La forme que tu choisis est la décision la plus lourde dans la façon dont un agent exploitera tes connaissances — trompe-toi et l’agent dilue une réponse claire, ou devine une valeur que tu as pourtant en stock. Cette page te donne le modèle mental pour savoir quand chaque forme est la bonne. Lis-la avant de charger un dossier de fichiers ; reviens-y quand tu es tenté de téléverser un tableur en PDF. ## Documents ou fiches structurées Un document est libre : le pipeline d’indexation extrait le texte, le découpe, calcule les embeddings et sert des passages par récupération au moment de répondre. L’agent voit des passages et les cite par source. C’est la bonne forme quand le contenu est de la prose — contrats, manuels, articles de base de connaissances, comptes rendus de réunion. Une fiche structurée est typée : l’entité a des champs connus (un client a un nom, un e-mail, un secteur ; un produit a un SKU, un prix, un stock). L’agent lit les champs directement, croise les entités entre elles et répond avec la valeur. C’est la bonne forme quand la source est une ligne de base de données — comptes, commandes, pièces, fiches fournisseurs. ## Les quatre entités intégrées Quatre onglets structurés côtoient **Documents** et **Entrées de connaissances** dans la base de connaissances : - **Clients** — les personnes et organisations avec qui tu fais affaire. - **Produits** — ce que tu vends. - **Fournisseurs** — ceux auprès de qui tu achètes. - **Sites web** — des sites publics qu’un crawler va chercher selon un planning ; la fiche porte le domaine et les réglages d’analyse, les pages indexées portent le contenu ([Exploration de sites web](/fr/platform/knowledge/crawling)). Les fiches structurées partagent les leviers de portée par équipe de la base de connaissances : une fiche limitée à une équipe est invisible hors de l’équipe, exactement comme un document limité à une équipe. ## Des modèles de contenu pour les formes sur mesure Quand les quatre entités intégrées ne conviennent pas, les modèles de contenu te laissent définir un type de fiche structurée sur mesure : nomme l’entité, déclare ses champs, règle l’accès champ par champ, et le nouveau type apparaît à côté des types intégrés. Les définitions vivent dans les [modèles de contenu de la gouvernance](/fr/platform/admin/governance/content-models). <Note> Les modèles de contenu coûtent de l’attention de gouvernance — l’accès et la politique de conservation de chaque champ sont à ta charge. Choisis-les quand la donnée est réellement une forme nouvelle, pas une variation légère d’une des quatre entités intégrées. </Note> ## En pratique — un agent CRM Un agent CRM qui répond à « où en est-on avec Acme ? » utilise les deux formes. L’entité Clients tient la fiche canonique — nom, contact principal, secteur, statut. Les documents tiennent les notes d’appel et les contrats. L’agent lit directement les champs du client, récupère des passages dans les documents et répond avec les deux : le statut structuré depuis Clients, le contexte le plus frais depuis la dernière note d’appel. Sans fiches structurées, l’agent doit retrouver Acme par son nom à travers des PDF et risque de confondre deux clients aux noms proches. Sans documents, l’agent connaît le statut d’Acme mais ne peut pas te dire ce qui s’est passé pendant l’appel de mardi. ## Quand y recourir | Choisis … quand | Documents | Fiche structurée | | ----------------------------------------------------------- | --------- | ---------------- | | La source est de la prose libre | ✓ | | | La source a des champs typés et tu veux des valeurs exactes | | ✓ | | Tu dois croiser de nombreuses fiches | | ✓ | | L’agent doit citer des passages par leur emplacement | ✓ | | ## Où cela s’inscrit Les données structurées sont la couture entre tes données opérationnelles et la surface agent. Utilise les quatre entités intégrées pour ce qu’elles couvrent ; passe aux [modèles de contenu](/fr/platform/admin/governance/content-models) quand une cinquième forme apparaît. La lecture suivante à mettre en file est [Documents](/fr/platform/knowledge/documents) — le pipeline d’indexation qui sert la moitié non structurée. # Concepts d’approbation Source: https://tale.dev/docs/fr/platform/approvals/concepts Une approbation est la couture entre l’initiative d’un agent et ton jugement : une carte qui apparaît dans le chat où l’action a été tentée, retenant cette action jusqu’à ce qu’une personne décide. Les agents proposent — une écriture de document, un appel d’API sortant, une exécution de workflow — et rien ne s’exécute tant que la carte est en attente. Le composeur du chat le dit explicitement : **Réponds à la demande en attente ci-dessus pour continuer**. Cette page est le modèle mental — ce qui déclenche une approbation, ce que la carte offre et ce qu’une décision laisse derrière elle. Les portes propres aux workflows vivent sur [Approbations dans les workflows](/fr/platform/automations/approvals-in-workflows) ; l’endroit où les exigences sont déclarées vit sur [Configurer les approbations](/fr/platform/approvals/configure). ## Ce qui déclenche une approbation Chaque carte vient d’un agent qui tente d’agir sur quelque chose qui survit à la conversation : - **Plans** — un agent propose un plan multi-étapes comme carte **Plan proposé** ; **Approuver et exécuter** le démarre. - **Écritures de documents** — une carte **Enregistrer dans les documents** retient les fichiers qu’un agent veut stocker ; rien n’atterrit dans le hub documentaire avant approbation. - **Écritures de connaissances** — une carte **Enregistrer dans la base de connaissances** retient un fait qu’un agent veut mémoriser à l’échelle de l’org. - **Appels d’intégration** — une opération marquée comme exigeant une approbation (des écritures sortantes, typiquement) tient avec les paramètres exacts affichés. - **Outils MCP** — un outil que le serveur marque **Nécessite une approbation** demande avant de s’exécuter. - **Création, mises à jour et exécutions de workflows** — les portes côté workflow, couvertes dans [Approbations dans les workflows](/fr/platform/automations/approvals-in-workflows). ## Les décisions sur une carte Chaque carte porte le payload exact de l’action — le fichier, le fait, les paramètres — et deux décisions : approuver (le bouton nomme l’action, comme **Exécuter le workflow** ou **Approuver et exécuter**) ou rejeter. Les cartes d’intégration ajoutent une troisième voie, **Suggérer des modifications** : décris ce qui ne va pas en texte libre et l’agent révise l’appel au lieu de l’abandonner. <Note> Les approbations se décident dans la conversation qu’elles interrompent — par la personne qui tient ce chat. Il n’y a ni boîte de réception d’approbations séparée ni routage vers un groupe d’approbateurs ; la personne pour qui l’agent travaille est la personne qui décide. </Note> ## Les états et la trace Une carte passe de **En attente** à **Exécution** puis **Terminé** — ou **Rejeté** — et garde son état résolu dans la transcription, si bien qu’un chat se relit comme le procès-verbal de ce qui a été autorisé. Chaque décision atterrit aussi dans le [journal d’audit](/fr/platform/admin/governance/audit-logs) avec l’acteur, l’action et l’horodatage. Les cartes résolues ne peuvent pas être rouvertes ; retenter signifie une proposition neuve et une carte neuve. ## Où cela s’inscrit Les approbations sont ce qui te laisse confier aux agents de vraies capacités — fichiers, API, workflows — sans céder le registre de qui a autorisé quoi. Lis ensuite [Configurer les approbations](/fr/platform/approvals/configure) pour voir où une exigence s’active, et [Approbations dans les workflows](/fr/platform/automations/approvals-in-workflows) pour les portes autour des workflows. # Configurer les approbations Source: https://tale.dev/docs/fr/platform/approvals/configure Les exigences d’approbation dans Tale sont déclaratives : chaque capacité porte son propre drapeau disant si un agent doit d’abord demander, et le drapeau voyage avec l’intégration ou le serveur qui fournit la capacité. Il n’y a pas de table centrale de règles à entretenir — cette page montre où vit chaque drapeau et comment lire ce qui demandera avant de s’exécuter. Le modèle de ce qu’est une carte d’approbation et de qui la décide vit sur [Concepts d’approbation](/fr/platform/approvals/concepts). Ce qui suit est la surface de configuration, capacité par capacité. ## Opérations d’intégration Chaque intégration déclare ses opérations, et chaque opération porte son propre drapeau d’approbation. Ouvre **Paramètres > Intégrations**, clique sur une intégration, et sa liste d’opérations badge celles marquées **Nécessite une approbation** — pour les connecteurs livrés, c’est le versant écriture : envoyer du courrier, poster des messages, créer des tickets. Les lectures s’exécutent sans carte ; les écritures marquées tiennent dans le chat avec leurs paramètres exacts jusqu’à ce que quelqu’un approuve. Pour une intégration personnalisée, le drapeau est `requiresApproval` par opération dans le `config.json` que tu empaquettes avec **Ajouter une intégration** — décide au moment de l’écriture lesquelles de ses opérations sont assez lourdes de conséquences pour demander. <Frame caption="Le catalogue des intégrations — la vue de détail de chaque entrée liste ses opérations et lesquelles exigent une approbation."> ![La page Intégrations des Paramètres sur l’onglet Toutes les intégrations montrant une grille de cartes de douze services connectables comme GitHub, Slack et Gmail.](/images/platform/integrations-catalog.webp) </Frame> ## Outils MCP Le manifeste d’un serveur MCP marque lesquels de ses outils exigent un accord. Ouvre **Paramètres > API > MCP**, déplie un serveur, et sa liste **Outils découverts** badge chaque outil marqué avec **Nécessite une approbation** — ceux-là demandent dans le chat chaque fois qu’un agent les appelle. Le drapeau vient de l’auteur du serveur ; connecter un serveur, c’est accepter son contrat d’outils, donc relis la liste avant d’en activer un. [Serveurs MCP](/fr/platform/integrations/mcp-servers) couvre l’enregistrement. ## Garde-fous d’écriture intégrés Certaines portes sont livrées actives et ne se configurent pas, parce que l’action est lourde de conséquences par nature : - **Écritures de documents** — un agent qui enregistre des fichiers dans le hub documentaire demande toujours (**Enregistrer dans les documents**). - **Écritures de connaissances** — un agent qui stocke un fait à l’échelle de l’org demande toujours (**Enregistrer dans la base de connaissances**). - **Création, mises à jour et exécutions de workflows** — un agent qui construit, modifie ou démarre un workflow demande toujours ; voir [Approbations dans les workflows](/fr/platform/automations/approvals-in-workflows). <Note> Le levier pour celles-ci n’est pas le drapeau d’approbation mais la capacité elle-même : un agent sans les outils de documents ou de workflows ne produit jamais la carte. Taille le [jeu d’outils](/fr/platform/agents/tools) de l’agent pour retirer la capacité entièrement. </Note> ## Vérifier ce qui demandera Avant de mettre un agent devant de vrais systèmes, lis ses capacités comme le ferait un approbateur : la liste d’opérations de l’intégration pour les écritures marquées, les **Outils découverts** du serveur MCP pour les outils marqués, et l’onglet outils de l’agent pour savoir s’il tient des outils d’écriture tout court. Le [journal d’audit](/fr/platform/admin/governance/audit-logs) enregistre ensuite chaque décision que produit l’installation. ## Où cela s’inscrit Configurer ici, c’est distribuer — les drapeaux vivent avec les intégrations et les serveurs qui possèdent les capacités. Lis [Concepts d’approbation](/fr/platform/approvals/concepts) pour le cycle de vie de carte que ces drapeaux produisent, et [Outils d’agent](/fr/platform/agents/tools) pour le versant capacité de la même frontière. # Recherche approfondie Source: https://tale.dev/docs/fr/platform/chat/deep-research La recherche approfondie est un mode du composeur qui confie une question à un agent **Chercheur** spécialisé. L’agent planifie le travail comme une liste de sous-questions, cherche sur le web ouvert avec Tavily, lit les pages les plus prometteuses, suit sa progression dans une carte de tâches que tu regardes en direct, et finit avec un rapport PDF qui cite chaque source utilisée. Va vers ce mode quand la question est ouverte, que la réponse a besoin de preuves, et que tu y passerais sinon une heure avec vingt onglets de navigateur. Cette page couvre la surface de la recherche approfondie de bout en bout — quand la choisir, à quoi ressemble le flux, le budget qui l’empêche de tourner à l’infini, et d’où viennent les sources citées. La mécanique de l’agent a la même forme que tout autre agent Tale (voir [Concepts d’agent](/fr/platform/agents/concepts)) ; ce qui est inhabituel ici, c’est le plan de tâches en direct et l’intégration Tavily qui alimente les recherches. ## Quand y recourir La recherche approfondie bat un chat ordinaire pour les questions où la valeur n’est pas le savoir existant du modèle mais l’assemblage d’informations récentes et sourcées. Trois signaux que c’est le bon mode : - La question est ouverte (« quel est le consensus actuel sur… », « compare les trois meilleurs… »). - Tu veux des citations — une affirmation sans URL est une devinette. - Tu acceptes d’attendre deux à dix minutes pour un rapport écrit plutôt qu’une réponse de chat. Pour des questions factuelles étroites (« quelle est la capitale du Sénégal »), un chat classique est plus rapide et tout aussi précis. Pour des questions sur tes propres données (« qu’a dit le client lors de l’appel de mardi dernier »), un agent avec des liaisons de [Connaissances](/fr/platform/agents/knowledge) est la bonne forme — la recherche approfondie ne lit que le web ouvert, pas ta base de connaissances. ## Ouvrir la recherche approfondie Ouvre le menu plus du composeur — les modes vivent sous son en-tête **Modes**, et **Deep research** y apparaît dès que l’agent Chercheur est disponible. Choisis-le et le composeur bascule vers l’agent Chercheur. Tape la question et envoie. Le panneau de réponse passe du streaming texte habituel à une carte **Plan de recherche** avec trois à sept tâches que l’agent a choisies comme sous-questions. <Frame caption="Les modes vivent dans le menu plus du composeur ; les entrées apparaissent quand leurs prérequis sont remplis."> ![Le menu plus du composeur ouvert, montrant une entrée Ajouter photos et fichiers et une section Modes listant le Mode Arène.](/images/platform/chat-composer-menu.webp) </Frame> Le mode est disponible quand un Éditeur ou un rôle supérieur a lié l’intégration **Tavily** sous [Paramètres > Intégrations](/fr/platform/integrations/overview) ; sans Tavily, l’entrée de menu nomme l’intégration manquante et un clic dessus ouvre les réglages d’intégrations. ## Le plan de recherche Le plan est une liste de tâches `pending` que l’agent a générées à partir de ta question. Pour les questions complexes, l’agent fait une pause après le premier plan et te demande de confirmer — une carte **Proceed with this plan?** apparaît avec un champ oui/non. Clique oui pour démarrer ; clique non et l’agent ne va pas plus loin. Les questions triviales sautent la confirmation. Une fois lancé, l’agent traite les tâches une par une : 1. Passe la tâche courante à `in_progress`. 2. Cherche jusqu’à trois fois sur Tavily pour cette tâche. 3. Lit jusqu’à deux des URL les plus prometteuses en entier via l’opération extract de Tavily. 4. Passe la tâche à `done` avec une conclusion en une phrase. La carte se met à jour en direct à mesure que chaque étape arrive. Tu peux regarder le raisonnement du modèle prendre forme ; si une nouvelle sous-question émerge en cours de route, l’agent l’ajoute à la liste. ## Recherches et extractions Tavily est le fournisseur de recherche web ouverte derrière la recherche approfondie — son API est optimisée pour les agents LLM et renvoie des résultats avec des snippets nettoyés et des scores par résultat. Deux opérations comptent : - **search** — requête en langue naturelle avec profondeur (`basic` ou `advanced`), thème (`general` ou `news`, avec une fenêtre `days` pour la fraîcheur), et une allowlist ou blocklist de domaines optionnelle. - **extract** — récupère le texte principal nettoyé pour une à cinq URL. L’agent l’appelle sur les deux meilleurs résultats par tâche quand un snippet ne suffit pas. Le palier gratuit de Tavily est de 1000 appels par mois ; les plans payants débloquent la profondeur `advanced` sur search et l’opération extract. Les étapes de configuration vivent sur la carte de setup de l’intégration sous **Paramètres > Intégrations**. ## Budget par exécution La recherche approfondie plafonne une exécution à : - **3 recherches + 2 extractions par tâche.** L’enveloppe d’intégration refuse les appels au-delà. - **40 étapes de raisonnement au total** sur toute l’exécution. - **25 minutes d’horloge.** Au-delà, l’agent s’arrête et synthétise avec ce qu’il a. - **60 appels d’intégration au total par exécution** comme plafond dur. Toucher l’une de ces limites arrête la phase de recherche et pousse l’agent en synthèse. S’il t’en faut plus, relance la question avec un périmètre plus serré ou découpe-la en deux questions. ## Le rapport PDF Quand chaque tâche est `done` (ou annulée, ou que le budget a heurté un mur), l’agent appelle l’outil **pdf** une fois pour produire un seul rapport structuré : - **Conclusion** — une à trois phrases répondant directement à la question. - **Key points** — trois à sept puces, chacune portant au moins une citation en ligne vers une source Tavily. - **Details** — l’analyse plus longue, groupée par sous-question. - **Sources** — une liste dédupliquée de chaque URL citée. Le PDF arrive comme une carte de pièce jointe dans le chat. L’agent ne colle pas le rapport dans le corps du message — la carte est le livrable. Une courte ligne de confirmation dans ta langue (« Recherche terminée — consulte le PDF ci-joint pour le rapport complet. ») pointe vers la carte. Pour les rapports en chinois, japonais et coréen, le jeu de polices du moteur de rendu PDF est incomplet ; dans ce cas, l’agent émet le même rapport structuré directement dans le chat et précise qu’un PDF traduit en anglais est disponible sur demande. ## Cas d’échec - **Tavily non connecté.** L’agent émet une ligne demandant à un Éditeur de connecter Tavily sous **Paramètres > Intégrations** et s’arrête. - **Quota Tavily épuisé.** L’intégration renvoie `INTEGRATION_BUDGET_EXHAUSTED` et l’agent passe à la synthèse avec ce qu’il a. Le palier gratuit touche cette limite vers le millième appel du mois. - **Une URL précise échoue à l’extraction.** La tâche concernée est marquée `failed` avec une raison ; les autres tâches continuent. - **Ton budget se vide.** L’exécution s’arrête et l’agent synthétise. La carte montre quelles tâches ont été sautées. ## Où ça s’inscrit La recherche approfondie est l’extrémité la plus lourde du composeur de chat — elle fait en dix minutes ce qu’un analyste ferait en un après-midi. Couple cette page avec [Concepts d’agent](/fr/platform/agents/concepts) (le modèle à quatre boutons sur lequel l’agent Chercheur est construit) et l’[Aperçu des intégrations](/fr/platform/integrations/overview) (où Tavily se tient à côté des autres intégrations que la ceinture d’outils de l’agent peut atteindre). Si tu veux construire ton propre agent de recherche plutôt qu’utiliser celui livré, [Créer un agent](/fr/platform/agents/create) parcourt la construction d’un agent de bout en bout. # Chats partagés Source: https://tale.dev/docs/fr/platform/chat/shared-threads Partager un chat crée un lien que toute personne de ton organisation peut ouvrir. Le visiteur voit le transcript complet en lecture seule ; il ne peut pas répondre, mais il peut dupliquer le chat en un chat à lui et continuer de là. Le mécanisme est assez léger pour un usage courant — partage une question et sa réponse comme tu partagerais un document. Cette page couvre la surface de partage de bout en bout : activer le partage, pour qui le lien fonctionne, la vue en lecture seule, et le geste de duplication qui transforme « je veux donner suite » en un nouveau chat. ## Partager un chat Clique sur **Partager** dans l’en-tête du chat. Le dialogue **Partager le chat** propose **Activer le partage** en bascule et, une fois le partage actif, le lien de partage avec **Copier le lien** et **Aperçu** — ce dernier ouvre la vue en lecture seule que verra le destinataire. Colle le lien dans le canal que ton équipe utilise. <Frame caption="Le dialogue Partager le chat — lien limité à l’organisation, copie et aperçu."> ![Le dialogue Partager le chat au-dessus d’un chat, montrant la bascule Activer le partage enclenchée, le lien de partage, et les boutons Copier le lien et Aperçu.](/images/platform/chat-share-dialog.webp) </Frame> **Toute personne de ton organisation disposant du lien peut consulter ce chat** — le lien est limité à l’organisation, pas à l’internet ouvert. Désactiver le partage plus tard invalide le lien ; les visiteurs atterrissent sur une page introuvable. ## Ce que voit le visiteur Le visiteur ouvre le lien et atterrit sur le chat avec une bannière : **Tu consultes un chat partagé en lecture seule**. Le transcript se lit exactement comme pour l’auteur, appels d’outils et citations compris. Le composeur est remplacé par une seule indication — **L'envoi d'un message créera ta propre copie de ce chat** — c’est le seul chemin vers l’avant. ## Dupliquer un chat partagé La seule action d’écriture du visiteur sur un chat partagé est **Dupliquer ce chat**. La duplication crée un nouveau chat appartenant au visiteur, avec le transcript complet copié comme contexte. L’original reste intact ; la duplication n’a aucun lien de retour vers l’original au-delà des messages dont elle hérite. Du côté du visiteur, la duplication est désormais un chat ordinaire — choix d’agent persistant, choix de modèle et outils se comportent comme dans n’importe quel chat qu’il aurait démarré lui-même. ## Quand le lien devient obsolète Désactiver le partage invalide le lien. Supprimer le chat source l’envoie à la [Corbeille](/fr/platform/admin/governance/trash) et le lien se casse ; restaurer le chat depuis la Corbeille ne restaure pas le lien — l’auteur réactive le partage si besoin. Les duplications existantes ne sont affectées par aucune de ces actions, parce qu’elles sont des chats indépendants. ## Où ça s’inscrit Les chats partagés sont la façon légère de passer un chat à un coéquipier sans quitter le produit. L’alternative plus lourde est d’amener le coéquipier dans un [Projet](/fr/platform/projects/overview) où chats, fichiers et agents sont partagés par défaut. Le partage sert les passations ponctuelles ; un Projet sert la collaboration continue sur le même travail. # Chat Source: https://tale.dev/docs/fr/platform/chat/overview Le chat est le point d’entrée quotidien à Tale. Tu l’ouvres, tu choisis un agent (ou aucun), tu tapes, et une réponse arrive en streaming — citations, appels d’outils et tout le reste. La plupart des utilisateurs passent plus de temps ici que dans n’importe quel autre onglet ; tout le reste de Platform existe pour nourrir le chat de quelque chose d’utile ou pour gouverner ce qu’il fait. <Frame caption="Un chat avec une réponse en streaming — la surface que toutes les autres fonctionnalités servent."> ![Un fil de chat montrant une question d’utilisateur sur des retours d’onboarding et une réponse de l’assistant contenant un tableau markdown de trois thèmes.](/images/platform/chat-thread-reply.webp) </Frame> ## Les parties de l’écran Le composeur, en bas, porte le sélecteur d’agents, le sélecteur de modèles (**Auto** laisse Tale choisir pour toi) et le champ de message. **Nouveau chat** dans la barre latérale démarre un chat tout neuf ; **Afficher l'historique** ouvre la liste de tous les chats que tu peux reprendre. Le Canevas s’ouvre à droite du thread quand l’agent produit quelque chose que la vue en ligne ne peut pas contenir — du code long, un diagramme, un document structuré. ## Les pages de cette section <CardGroup cols="2"> <Card title="Bases du chat" icon="message-circle" href="/fr/platform/chat/basics"> Ce qui se passe entre l’envoi et l’arrivée de la réponse — composer, résolution du modèle, streaming, citations. </Card> <Card title="Pièces jointes" icon="paperclip" href="/fr/platform/chat/attachments"> Les types de fichiers pris en charge, où atterrissent les téléversements, quand le contenu est indexé plutôt qu’inséré tel quel. </Card> <Card title="Agents dans le chat" icon="bot" href="/fr/platform/chat/agents-in-chat"> Choisir des agents, ponctuel versus persistant, changer en cours de thread, appels de sous-agents. </Card> <Card title="Mode Arène" icon="swords" href="/fr/platform/chat/arena-mode"> La comparaison de modèles côte à côte, et comment les verdicts remontent dans l’analyse des retours. </Card> <Card title="Mode vocal" icon="mic" href="/fr/platform/chat/voice-mode"> Parler au lieu de taper — les passations STT et TTS et la frontière de confidentialité. </Card> <Card title="Chats partagés" icon="share-2" href="/fr/platform/chat/shared-threads"> Partager un chat avec le reste de l’organisation, dupliquer un chat partagé en un chat à toi. </Card> <Card title="Amorces et prompts" icon="list-plus" href="/fr/platform/chat/starters-and-prompts"> Les amorces de conversation des agents et la bibliothèque de prompts. </Card> <Card title="Volet Canevas" icon="panel-right" href="/fr/platform/chat/canvas-pane"> Quand le Canevas s’ouvre, et ce qui obtient un Canevas plutôt qu’un rendu en ligne. </Card> </CardGroup> ## Où ça s’inscrit Le chat est la surface que chaque autre fonctionnalité de Platform finit par servir. Les agents façonnent ses réponses, les Connaissances alimentent ses citations, les Approbations l’interrompent pour des vérifications humaines, Conversations est une boîte de réception sœur pour les canaux clients plutôt que pour tes propres chats. La page à mettre en favori en premier est [Bases du chat](/fr/platform/chat/basics) — une fois compris le chemin du composeur à la réponse, chaque autre page de chat se lit comme une variation autour. # Amorces et prompts Source: https://tale.dev/docs/fr/platform/chat/starters-and-prompts Un chat tout neuf montre deux surfaces au-delà du composeur : les **Amorces** de l’agent (des prompts d’exemple à un clic) et la **Bibliothèque de prompts** (tes prompts enregistrés). Les deux transforment le problème de l’écran vide — « qu’est-ce que je vais bien pouvoir demander » — en un seul clic qui dépose du texte fonctionnel dans le composeur. Cette page couvre les deux surfaces. Elles vivent côte à côte dans l’UI pour une raison : les amorces sont les points d’entrée choisis par l’auteur de l’agent, la bibliothèque est ta réserve personnelle, et la plupart des équipes finissent par utiliser les deux ensemble. ## Amorces de conversation <Frame caption="Un chat tout neuf avec les amorces de l’agent choisi — un clic dépose le texte dans le composeur."> ![L’écran de nouveau chat vide montrant les quatre amorces de conversation de l’Assistant au-dessus du composeur.](/images/platform/chat-starters-empty.webp) </Frame> Chaque agent peut embarquer jusqu’à quatre **Amorces** — de courts prompts d’exemple que l’auteur de l’agent a jugés être de bons points d’entrée. Elles apparaissent sur l’écran de chat vide quand l’agent est choisi ; en toucher une dépose le texte de l’amorce dans le composeur et te laisse l’éditer avant d’envoyer. Les amorces appartiennent à l’agent, pas au chat — le même agent montre les mêmes amorces partout. Les auteurs d’agents entretiennent les amorces sur l’onglet **Amorces** de l’éditeur de l’agent ; voir [Amorces de conversation](/fr/platform/agents/conversation-starters) pour le côté auteur. Les membres voient ce que l’auteur a publié ; il n’y a pas de surcharge par utilisateur. ## La bibliothèque de prompts La **Bibliothèque de prompts** est ta collection personnelle de prompts réutilisables. Enregistre le message que tu t’apprêtes à envoyer avec **Enregistrer le prompt** ; rappelle-le plus tard avec **Bibliothèque de prompts** sur le composeur. Les prompts peuvent porter des espaces réservés que la bibliothèque te demande de remplir au moment de l’insertion, ce qui transforme un modèle « traduis le texte suivant en allemand » en workflow à un clic. Les prompts que tu enregistres sont privés par défaut. Partager un prompt avec l’organisation le rend visible dans la bibliothèque de chacun ; la liste des prompts de l’organisation vit dans la [Bibliothèque de prompts](/fr/platform/workspace/prompt-library) (la page workspace) pour parcourir et taguer. ## Catégories Les amorces comme les prompts peuvent porter une catégorie — un court tag comme `Sales`, `Support`, `Marketing` qui les groupe dans le sélecteur. Les catégories sont définies par l’organisation et gérées dans les réglages ; un agent ou un prompt sans catégorie se range dans le compartiment par défaut. ## Où ça s’inscrit Amorces et prompts sont l’échafaudage de l’écran vide autour du Chat. La moitié bibliothèque chevauche la [Bibliothèque de prompts](/fr/platform/workspace/prompt-library) — mêmes données, autre surface. Les amorces vivent sur l’agent et se gèrent depuis sa page [Amorces de conversation](/fr/platform/agents/conversation-starters). La lecture suivante dépend du côté où tu te trouves — auteur ou utilisateur. # Bases du chat Source: https://tale.dev/docs/fr/platform/chat/basics Cette page est le modèle mental pour tout ce qui vit dans l’onglet Chat. Elle nomme les parties du composeur, suit un message de la touche pressée à la réponse en streaming, et explique comment un chat est stocké une fois arrivé — lis-la une fois et le reste des pages de chat se lit comme des variations sur le même flux. <Frame caption="L’onglet Chat avec une réponse en streaming au-dessus du composeur."> ![Un fil de chat montrant une question d’utilisateur sur des retours d’onboarding et une réponse de l’assistant contenant un tableau markdown de trois thèmes.](/images/platform/chat-thread-reply.webp) </Frame> ## Le composeur Le composeur est la bande de saisie en bas de l’écran. Trois contrôles comptent : le sélecteur d’agents à gauche, le sélecteur de modèles à côté, et le champ de message avec l’envoi à droite. Les pièces jointes arrivent par collage, glisser-déposer ou le contrôle d’ajout — voir [Pièces jointes](/fr/platform/chat/attachments) pour ce qui est accepté. <Frame caption="Les contrôles du composeur — le champ de message, les sélecteurs d’agents et de modèles, et l’envoi."> ![Le composeur de chat vide, dont le texte d’invite propose de poser une question sur les contacts, les produits ou les documents, au-dessus d’une barre d’outils qui porte les boutons de pièce jointe et de bibliothèque de prompts, le sélecteur d’agents, le sélecteur de modèles, et les boutons de sourdine, de micro et d’envoi.](/images/platform/chat-composer.webp) </Frame> ## Choisir un agent Le sélecteur d’agents filtre par nom à mesure que tu tapes ; le défaut est un **Assistant** sans agent, qui utilise le modèle de chat par défaut de l’organisation et aucune connaissance ni outil supplémentaire. Choisir un agent avant le premier message le rend persistant pour tout le chat ; en choisir un en cours de chat s’applique à partir du message suivant. <Note> Il n’existe pas de bascule « rétablir sans agent » — choisis **Assistant** pour revenir en arrière. Les règles complètes vivent dans [Agents dans le chat](/fr/platform/chat/agents-in-chat). </Note> ## Choisir un modèle Le sélecteur de modèles liste ce que l’agent (ou l’organisation, quand aucun agent n’est choisi) autorise. Chaque modèle porte un tag — **Chat**, **Vision**, **Génération d'images**, **Embedding** — qui signale ce à quoi il est bon. **Auto** choisit le modèle primaire de l’agent ; quand le primaire est limité en débit ou indisponible, Tale redescend l’ordre de repli que l’agent définit. <Warning> Choisir un modèle sans vision quand le message inclut une image abandonne l’image en silence — la réponse se lit comme si l’image n’avait jamais été envoyée. </Warning> ## Lire la réponse La réponse arrive en streaming, token par token. Quand l’agent raisonne avant de répondre, une ligne de réflexion pliable apparaît au-dessus de la réponse. Les appels d’outils s’affichent comme des boîtes pliées que tu peux déplier pour lire ce que l’agent a fait ; la sortie d’**Exécuter du code** atterrit dans le Canevas, à droite, comme **Sortie de code** dans son arborescence de fichiers. Quand l’agent récupère des connaissances, des citations s’attachent aux phrases qu’elles soutiennent — survoler une citation montre le titre de la source, cliquer ouvre la source. Les instructions de l’agent n’apparaissent jamais dans la réponse rendue ; elles restent une couche en dessous et façonnent le comportement plutôt que le texte. ## Les questions de l’agent Un agent doté de l’outil human input peut s’interrompre en pleine tâche pour te poser une question — une carte **Question** apparaît dans le chat avec les champs dont l’agent a besoin, et la génération attend ta réponse. Remplis le formulaire et clique sur **Soumettre la réponse**, ou clique sur **Répondre différemment** pour objecter en texte libre. Si ta réponse était fausse ou incomplète, clique sur **Modifier la réponse** sur la carte répondue — le formulaire se rouvre prérempli, et **Mettre à jour la réponse** relance l’agent, la réponse corrigée remplaçant l’ancienne. La carte garde chaque réponse précédente : feuillette les versions avec les flèches à côté de la réponse, comme pour les messages modifiés. ## Conversations versus chats À l’intérieur du Chat, l’unité est un **chat** — c’est le mot que chaque bouton et chaque toast utilise. Le modèle de données derrière s’appelle `threads`, et le slug d’URL est `threads/$threadId` ; la doc suit l’UI et dit « chat » dans la prose. La boîte de réception des canaux clients qu’ajoute une automatisation d’e-mail installée est une autre surface — une conversation là-bas est un fil client, pas un chat ; voir [Automatisations livrées](/fr/platform/automations/builtin) pour le sens de boîte de réception. ## Historique et recherche **Afficher l'historique** au-dessus du composeur ouvre la barre latérale d’historique — chaque chat que tu peux reprendre dans cette organisation, du plus récent au plus ancien ; en sélectionner un ouvre le transcript complet. La recherche y filtre par titre ; la recherche en texte intégral dans les corps de messages est une opération par chat, pas à l’échelle de l’organisation. Renommer un chat pose un titre personnalisé qui remplace celui généré par le modèle ; supprimer un chat le déplace dans la [Corbeille](/fr/platform/admin/governance/trash), où la rétention le balaie après la fenêtre de grâce. ## Où ça s’inscrit Bases du chat est la page que tout le reste de la section affine : [Agents dans le chat](/fr/platform/chat/agents-in-chat) creuse le sélecteur, [Pièces jointes](/fr/platform/chat/attachments) ce que fait le téléversement, [Mode vocal](/fr/platform/chat/voice-mode) les passations STT et TTS autour du même composer. Si tu es venu ici pour construire un agent plutôt que pour en utiliser un, saute à [Concepts d’agent](/fr/platform/agents/concepts) — le modèle mental à quatre boutons est le socle sur lequel repose chaque chat avec un agent. # Mode Arène Source: https://tale.dev/docs/fr/platform/chat/arena-mode Le Mode Arène exécute le même prompt contre deux modèles à la fois et te demande quelle réponse est la meilleure. Le verdict alimente l’analyse des retours de l’organisation ; avec le temps, les données disent quel modèle l’équipe préfère vraiment pour quel type de question, indépendamment du ressenti de chacun. Va vers l’Arène quand le choix d’un modèle a été un débat plutôt qu’une décision — comparer des réponses côte à côte casse l’impasse avec des preuves plutôt qu’avec des opinions. Pour le travail ordinaire, le sélecteur de modèles classique suffit ; la valeur de l’Arène, ce sont les verdicts qu’elle produit, pas la vue de comparaison elle-même. ## Comment l’Arène s’affiche Ouvre le menu plus du composeur et choisis **Mode Arène** — le composeur fait pousser deux sélecteurs de modèles étiquetés **Modèle A** et **Modèle B**. Envoyer un message exécute les deux modèles en parallèle ; l’écran se sépare et chaque réponse arrive en streaming dans sa propre colonne. Une fois les deux terminées, une rangée de verdict apparaît sous les colonnes avec quatre boutons : **A est meilleur**, **B est meilleur**, **Égalité**, **Les deux sont mauvais**. <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.](/images/platform/chat-arena-split.webp) </Frame> <Note> L’Arène a besoin d’un agent précis — choisis-en un à la place d’**Auto** dans le sélecteur d’agents avant de l’activer. </Note> ## Choisir les concurrents Les deux sélecteurs sont indépendants — n’importe quel modèle tagué chat que la politique de l’agent autorise est valable de chaque côté. Choisir le même modèle des deux côtés est permis (utile pour tester des différences de température si l’agent expose ça), mais la plupart des comparaisons traversent fournisseurs ou tailles. Les instructions, les connaissances et les outils de l’agent s’appliquent aux deux colonnes ; seul le modèle sous-jacent diffère. ## Émettre un verdict Le verdict se donne en un clic. **A est meilleur** et **B est meilleur** parlent d’eux-mêmes ; **Égalité** sert quand les deux réponses se valent à peu près ; **Les deux sont mauvais** quand aucune n’est acceptable. Le bouton que tu cliques enregistre le verdict et résout le chat sur la colonne gagnante — le message suivant que tu envoies ne va qu’à ce modèle. **Égalité** ou **Les deux sont mauvais** laissent les deux colonnes actives pour un tour de plus. ## Où les verdicts apparaissent Les verdicts remontent dans l’[Analyse des retours](/fr/platform/admin/governance/feedback-analytics) sous **Verdicts d'arène**, à côté d’un tableau **Top duels de modèles** qui classe les paires par taux de victoire. Les données sont à l’échelle de l’organisation, pas par utilisateur, donc les verdicts d’une petite équipe peuvent peser plus lourd que les défauts d’une grande quand un admin s’appuie sur le tableau pour fixer le modèle par défaut de l’organisation. ## Quand y recourir | Utilise … quand | Mode Arène | Sélecteur classique | | ----------------------------------------------------------------------- | ---------- | ------------------- | | Tu décides quel modèle mettre par défaut | ✓ | | | Tu soupçonnes une régression de modèle après une mise à niveau | ✓ | | | Tu sais déjà quel modèle tu veux ; tu veux juste une réponse maintenant | | ✓ | | La requête est courte et ordinaire | | ✓ | ## Où ça s’inscrit L’Arène est la boucle de retour légère par-dessus le choix de modèle. La surface lourde est l’[Analyse des retours](/fr/platform/admin/governance/feedback-analytics) — c’est là que les verdicts que tu émets deviennent un graphique avec lequel quelqu’un argumentera plus tard sur les défauts. Si c’est toi qui liras le graphique, fais une poignée de tours d’Arène avant de le lire ; les verdicts que tu émets toi-même te diront si le cadrage du tableau correspond à ton expérience. # Mode vocal Source: https://tale.dev/docs/fr/platform/chat/voice-mode Le mode vocal transforme le composeur en microphone. Tu parles, Tale transcrit, l’agent répond en texte, et la réponse est lue à voix haute en retour. Toute la boucle se fait sans les mains — utile quand tu marches, tu conduis (légalement), tu cuisines, ou tu en as assez de taper. Le chemin vocal du composeur traverse deux fournisseurs de modèles (reconnaissance vocale, puis synthèse) et un ou deux appels d’agent entre les deux. Savoir quel fournisseur tient quel morceau de l’audio fait la différence entre « c’est pratique » et « c’est imprudent » pour les données de ton organisation. ## Comment le mode vocal s’exécute Touche l’icône microphone sur le composeur et l’enregistrement démarre ; touche-la à nouveau pour arrêter. Tale téléverse le clip audio, le modèle de reconnaissance vocale le transcrit, et la transcription devient le message suivant du chat — exactement comme si tu l’avais tapée. L’agent répond en texte ; une fois la réponse complète, Tale la route vers un modèle de synthèse et joue l’audio en retour. Pendant que la réponse défile, **Arrêté** met fin à la lecture plus tôt ; **Lire la sortie vocale** rejoue la dernière réponse. ## Passations STT et TTS Deux choix de modèles comptent, et ils se configurent séparément du modèle de chat. La **reconnaissance vocale** tourne une fois par message parlé — l’audio est téléversé, transcrit, et la transcription est ce que l’agent voit. La **synthèse vocale** tourne une fois par réponse — Tale découpe la réponse en segments de sortie vocale et streame l’audio en retour. L’agent lui-même ne change pas ; le mode vocal est une enveloppe autour du même composer. ## Choisir la voix Chaque agent peut épingler une voix préférée dans ses réglages ; sans choix par agent, le mode vocal utilise la voix par défaut de l’organisation. Les voix sont liées à des fournisseurs TTS précis — changer de fournisseur change les voix disponibles. Si un chat utilise un agent dont le fournisseur de voix n’est plus configuré, Tale retombe sur la voix par défaut de l’organisation plutôt que de faire échouer la réponse. ## La frontière de confidentialité Le clip audio que tu enregistres quitte ton appareil. Il est téléversé dans le stockage de Tale, envoyé au fournisseur de reconnaissance vocale que tu as configuré, et la transcription est conservée dans l’historique du chat à côté des messages tapés. L’audio lui-même est conservé selon la politique de rétention de l’organisation. Les réponses partent vers le fournisseur de synthèse en texte brut ; la réponse audio est streamée vers ton appareil et n’est pas stockée sur disque par défaut. <Warning> Les organisations avec des règles strictes de sortie de région devraient choisir des fournisseurs STT et TTS dans la même région que le reste de la pile — voir [Résidence des données](/fr/cloud/data-residency). </Warning> ## Quand la voix bat le texte La voix est plus rapide que le clavier pour des questions courtes et conversationnelles, et nettement plus lente que le clavier pour du code, des listes, ou tout ce que tu recopierais. Les réponses vocales plafonnent à une limite de segments — les réponses longues s’arrêtent en cours de lecture et affichent un avis. Va vers la voix quand la réponse sera entendue une fois puis oubliée ; va vers le texte quand la réponse doit être parcourue ou conservée. ## Quand y recourir | Utilise … quand | Mode vocal | Texte | | --------------------------------------------------------- | ---------- | ----- | | Tu as les mains prises et tu veux un fait rapide | ✓ | | | La réponse sera une longue liste ou un bloc de code | | ✓ | | La réponse de l’agent nourrira une tâche écrite plus tard | | ✓ | | Tu pratiques une langue et tu veux l’entendre | ✓ | | ## Où ça s’inscrit Le mode vocal est l’une des trois « formes d’entrée » sur le même composer : le texte (le défaut), les pièces jointes et la voix. L’histoire de la confidentialité compte le plus ici parce que deux fournisseurs supplémentaires touchent les données, donc la page à lire ensuite est [Résidence des données](/fr/cloud/data-residency) sur Cloud ou [Configuration → fournisseurs](/fr/self-hosted/configuration/providers) en auto-hébergé, selon l’édition que tu fais tourner. # Agents dans le chat Source: https://tale.dev/docs/fr/platform/chat/agents-in-chat Choisir un agent dans le Chat fait la différence entre interroger un Assistant générique et interroger quelque chose que l’organisation a façonné pour un domaine. Le sélecteur d’agents est le contrôle le plus utilisé du composeur ; les règles qui décident quel agent apparaît, quand un agent persiste, et ce qui se passe quand tu changes en cours de chat font l’objet de cette page. <Frame caption="Le sélecteur d’agents ouvert au-dessus du composeur — Auto, les agents installés et le raccourci Catalogue."> ![Le sélecteur d’agents ouvert au-dessus du composeur de chat, montrant un champ de recherche, une entrée Auto, l’Assistant sélectionné, une entrée Assistant d’automatisation et un bouton Parcourir les automatisations.](/images/platform/chat-agent-picker.webp) </Frame> ## Le sélecteur d’agents Clique sur la puce d’agent du composeur (son nom accessible est **Sélectionner un agent**) et le sélecteur s’ouvre avec **Rechercher des agents** en haut. La liste montre **Auto** — Tale route chaque message vers l’agent qui colle le mieux — suivi de chaque agent auquel tu as accès et qui est marqué **Visible dans le chat** ; les agents de code ont leur propre section **Agents de code** dès que l’un d’eux est visible. Les agents sans cette bascule existent dans l’organisation mais ne montent jamais ici, ce qui garde la liste courte. **Parcourir les automatisations**, en bas, mène au [catalogue des automatisations](/fr/platform/automations/catalog) — les nouveaux agents arrivent au sein d’une automatisation que tu installes. ## « Visible dans le chat » Chaque agent porte une bascule **Visible dans le chat** sur la page **Général** de son éditeur. La désactiver ne désactive pas l’agent — les automatisations et les workflows peuvent toujours l’appeler, et les appels de sous-agents depuis d’autres agents fonctionnent encore — elle cache seulement l’agent du sélecteur du chat. La raison : les organisations finissent avec des dizaines d’agents que l’utilisateur moyen ne choisit jamais (agents utilitaires appelés par d’autres agents, agents liés à un workflow précis), et tous les afficher noierait les choix quotidiens. ## Ponctuel versus persistant Choisir un agent **avant** le premier message d’un chat le rend persistant — chaque message suivant du même chat va au même agent. En choisir un **en cours de chat** l’applique au message suivant et à tout ce qui suit, jusqu’au prochain changement. <Note> Il n’existe pas de geste « utilise cet agent une fois puis reviens » — pour rendre la main, choisis explicitement **Assistant** (ou **Auto**) dans le sélecteur. Le transcript garde l’agent par message, donc un chat avec un changement en cours de route se lit comme deux agents qui collaborent. </Note> ## Changer en cours de thread Les connaissances et les outils de l’agent changent avec le sélecteur, mais pas l’historique de la conversation. Le nouvel agent lit tout ce qui précède — tes messages et les réponses de l’agent précédent — et continue à partir de là. C’est utile pour les passations : un agent de tri répond au premier message, tu passes à un spécialiste pour la suite, et le spécialiste a tout le contexte sans que personne ne copie-colle. ## Appels de sous-agents Les instructions d’un agent peuvent inclure un outil sous-agent ; quand c’est le cas, l’agent primaire peut déléguer une partie du travail sans que l’utilisateur choisisse quoi que ce soit. Les appels de sous-agents s’affichent dans la réponse comme des appels d’outils pliés — tu vois ce qui a été délégué et ce qui est revenu, pas une seconde conversation complète. Les règles de délégation et le modèle de prévention des boucles vivent sur [Délégation d’agent](/fr/platform/agents/delegation). ## Quand opter pour chaque forme | Utilise … quand | Chat | Projets | Conversations | | ------------------------------------------------------- | ---- | ------- | ------------- | | Tâche personnelle, question ponctuelle | ✓ | | | | Espace de travail partagé en équipe, threads récurrents | | ✓ | | | Entrée depuis un canal client (e-mail, webhook) | | | ✓ | ## Où ça s’inscrit Agents dans le chat est la moitié côté utilisateur de l’histoire des agents — ce que fait le sélecteur, ce qui s’affiche, comment la persistance fonctionne. La moitié côté construction est [Concepts d’agent](/fr/platform/agents/concepts) : les quatre boutons qui déterminent ce qu’un agent fait une fois choisi. Si tu es venu ici pour construire l’agent que tu aimerais voir dans le sélecteur, c’est la lecture suivante. # Pièces jointes Source: https://tale.dev/docs/fr/platform/chat/attachments Les pièces jointes permettent à un chat de référencer un fichier sans renvoyer l’utilisateur vers un autre onglet. Tu colles, tu glisses, ou tu choisis **Ajouter photos et fichiers** dans le menu plus du composeur ; le fichier accompagne le message et Tale le route vers le bon pipeline. La plupart des types de fichiers atterrissent tels quels dans l’entrée du modèle ; les fichiers volumineux ou structurés sont indexés et lus par extraits. Cette page couvre uniquement le mécanisme de téléversement sur le composeur. Les documents téléversés dans [Connaissances](/fr/platform/knowledge/documents) suivent un flux séparé avec une indexation persistante — les pièces jointes de chat restent limitées au chat qui les a reçues. ## Un téléversement déroulé Colle un PDF dans le composeur. Le composeur affiche une puce avec le nom du fichier et un spinner ; la puce se stabilise une fois le fichier arrivé dans le stockage de Tale. Envoie le message, et l’agent reçoit une vue texte extraite du PDF, en ligne avec ton prompt. Si le fichier dépasse le budget de contexte en ligne, Tale l’indexe et l’agent lit des chunks à la demande via son outil de récupération. ## Types pris en charge Trois familles : les **images**, les **documents structurés** (PDF, DOC/DOCX, ODT, XLS/XLSX, PPT/PPTX) et les **fichiers de type texte** (texte brut, markdown, code source, CSV, JSON, YAML). Les images vont au modèle vision que le chat utilise ; le sélecteur de modèles doit être sur un modèle capable de vision, sinon l’image est abandonnée en silence. Les documents structurés sont extraits en texte — diagrammes, pages scannées et objets embarqués relèvent du meilleur effort. Les fichiers de type texte atterrissent tels quels. ## Où vivent les téléversements Chaque pièce jointe est stockée dans le stockage objet de Tale et liée au chat qui l’a reçue, et elle est aussi copiée dans la sandbox du chat sous `/user/uploads/<name>`. C’est sur cette seconde copie que travaillent les outils `file_read`, `file_list` et `run_code` de l’agent : les octets réels, pas seulement la vue texte extraite qui accompagne ton prompt en ligne. Supprimer le chat déplace les pièces jointes dans la [Corbeille](/fr/platform/admin/governance/trash) avec l’historique des messages ; la restauration les ramène. Il n’existe pas de bibliothèque « pièces jointes de chat » séparée — pour partager un document entre plusieurs chats, téléverse-le dans [Connaissances](/fr/platform/knowledge/documents) et lie-le à un agent. ## RAG versus tel quel Les petits fichiers texte et les documents structurés sous le budget en ligne de l’agent sont insérés tels quels. Les plus gros sont découpés en chunks, embarqués et indexés ; l’agent récupère les chunks pertinents au moment de la réponse et les cite. La frontière dépend du modèle — les modèles à long contexte avalent davantage en entier. Quand l’agent récupère depuis une pièce jointe plutôt que de la lire entière, les citations pointent vers des plages de chunks dans le fichier d’origine. ## Référencer des documents de la base de connaissances avec @ <Frame caption="Taper @ ouvre le sélecteur de la base de connaissances au-dessus du composeur."> ![Le composeur de chat avec une arobase tapée et le sélecteur de la base de connaissances ouvert, listant trois documents texte indexés.](/images/platform/chat-mention-picker.webp) </Frame> Taper `@` dans le composeur ouvre un sélecteur sur les connaissances indexées de l’organisation — réparti en une section **Documents** et une section **Dossiers**. Tape pour filtrer par nom ; `@fichier` épingle un document sous une puce **Connaissances**, `@dossier` épingle un dossier et tout ce qui est indexé dessous sous une puce **Dossier**. À l’envoi, Tale vérifie ton accès, restreint la récupération de cette réponse exactement aux entrées épinglées — un dossier s’étend à son sous-arbre indexé — et injecte les passages pertinents même quand le mode connaissances de l’agent est désactivé, car une mention explicite l’emporte sur la configuration de récupération de l’agent. Jusqu’à cinq entrées, documents et dossiers confondus, peuvent être épinglées par message. Les puces sont la source de vérité : supprimer le texte `@Titre` du message ne désépingle pas la référence — retire plutôt la puce. Le sélecteur ne propose que des documents dont l’indexation est terminée et auxquels tes équipes ont accès. Dans un chat de projet, il liste en plus les fichiers et dossiers propres au projet, en tête ; les fichiers d’un projet restent limités au projet et n’apparaissent jamais dans le sélecteur `@` d’un chat en dehors de celui-ci — voir [Gérer les fichiers du projet](/fr/platform/projects/manage-files). La référence vaut par message ; une question de suivi sans mention retombe sur le périmètre de connaissances normal de l’agent. ## Où ça s’inscrit Les pièces jointes sont le moyen léger, limité au chat, d’amener un fichier dans une réponse. L’équivalent lourd, à l’échelle de l’organisation, est [Documents](/fr/platform/knowledge/documents) — même pipeline d’indexation, mais lié à des agents au lieu d’un seul chat. La page à lire ensuite dépend de ce que tu cherches à faire — si le fichier compte une fois, attache-le ici ; s’il comptera encore, téléverse-le dans Connaissances et laisse un agent le référencer depuis chaque chat. # Volet Canevas Source: https://tale.dev/docs/fr/platform/chat/canvas-pane Le **Canevas** est un second volet qui s’ouvre à droite du thread de chat. Il apparaît quand la réponse contient un contenu que le thread linéaire ne peut pas bien tenir — un long bloc de code, un diagramme Mermaid, un document structuré, un script Python exécutable. Les réponses en ligne restent courtes et lisibles ; tout le reste s’écarte du chemin. Le Canevas n’est pas un composeur plus riche, et ce n’est pas un endroit où tu édites à la main. C’est une vue vivante de l’espace de travail du chat — les fichiers que l’agent écrit, les fichiers que tu téléverses et les fichiers que les exécutions de code produisent — et tu le vois sans avoir à le demander. ## Ce qu’est le Canevas Le Canevas s’ouvre automatiquement la première fois qu’une réponse produit du contenu digne du Canevas. Il a deux parties : à gauche une arborescence de fichiers, à droite un lecteur. L’arborescence regroupe les fichiers de l’espace de travail du chat selon leur origine — les **Fichiers IA** que l’agent a écrits (`/user/code`), les **Téléversés** que tu as joints ou épinglés avec `@` (`/user/uploads`), et la **Sortie de code** qu’une exécution a produite (`/user/output`) ; les groupes vides restent masqués. Choisis un fichier et il s’ouvre dans le lecteur, où tu bascules entre **Source** et **Aperçu** pour lire le code brut ou voir le résultat rendu, et où **Télécharger** enregistre ce fichier. ## Quand il s’ouvre automatiquement Le Canevas s’ouvre pour plusieurs types de rendu que le thread en ligne encombrerait : **Code** (n’importe quel langage), **HTML**, diagrammes **Mermaid**, **SVG**, longs documents **Markdown** produits par l’agent, et scripts exécutables — **Python (sandbox)**, **Node (sandbox)**, **Script (sandbox)**. `run_code` s’exécute sur l’espace de travail partagé du chat — il lit les scripts que l’agent a écrits sous `/user/code` et récupère ce qu’une exécution laisse dans `/user/output`, si bien que les résultats apparaissent comme des lignes **Sortie de code** dans l’arborescence de fichiers, pas seulement à côté du script ; une exécution peut aussi se contenter d’installer des paquets comme étape distincte, en affichant **Installation des dépendances** pendant ce temps. Seuls les fichiers écrits par l’agent et les sorties de code ouvrent le Canevas automatiquement — les fichiers que tu téléverses apparaissent dans l’arborescence mais ne s’emparent pas de l’écran. Les courts extraits que le thread en ligne peut tenir ne déclenchent pas le Canevas — un script de vingt lignes s’affiche en ligne avec son propre contrôle **Copier**, comme ci-dessous. <Frame caption="Un script court reste en ligne — le Canevas est pour la sortie qui déborde du thread."> ![Une réponse de chat contenant un bloc de code Python avec coloration syntaxique, rendu en ligne avec un bouton Copier, sans que le volet Canevas s’ouvre.](/images/platform/chat-code-reply.webp) </Frame> ## Éditer dans le Canevas Le Canevas est une surface de rendu pour ce que l’agent a produit. Éditer le contenu rendu revient à demander une révision à l’agent — un message de suivi dans le thread (« passe le timeout à 30 secondes », « rends le diagramme horizontal ») déclenche une nouvelle génération qui remplace le contenu du Canevas. Il n’y a pas de mode d’édition directe ; l’agent possède les fichiers qu’il écrit, et les fichiers que tu téléverses restent exactement tels que tu les as envoyés. ## Persistance entre les visites du chat Le contenu du Canevas fait partie du chat, pas d’un fichier séparé. Rouvrir le chat plus tard rouvre le Canevas avec le contenu le plus récent ; passer à un autre chat ferme le volet Canevas jusqu’à ce que ce chat produise ou porte son propre contenu Canevas. Partager le chat avec **Partager le chat** emporte le Canevas — le visiteur voit la même bascule Source / Aperçu, en lecture seule. ## Où ça s’inscrit Le Canevas est la réponse à « que se passe-t-il quand la réponse est trop grosse pour le thread ». Il se compose avec tout le reste du Chat — agents, pièces jointes, voix, chats partagés — sans que ces fonctionnalités aient besoin de le connaître. La lecture qui compte parfois ensuite : [Construire un outil personnalisé](/fr/tutorials/developer/build-a-custom-tool) parcourt de bout en bout, sur une instance neuve, un agent qui produit du Python exécutable dans le Canevas. # Intégrations Source: https://tale.dev/docs/fr/platform/integrations/overview Les intégrations sont les ponts entre Tale et le reste de ta stack : les agents les appellent comme outils, les workflows les appellent à leurs étapes, et le pipeline de connaissances tire des documents à travers elles. L’org connecte chacune une seule fois sous **Paramètres > Intégrations** ; à partir de là, tout dans Tale peut l’utiliser sans se ré-authentifier. Cette vue d’ensemble nomme le catalogue livré et les deux façons de l’étendre. <Frame caption="Paramètres > Intégrations sur l’onglet Toutes les intégrations — le catalogue complet, chaque carte à un Connecter de distance."> ![La page Intégrations des Paramètres montrant un champ de recherche, un bouton Ajouter une intégration et une grille de cartes de douze services dont Confluence, GitHub, Gmail, Slack et Twilio.](/images/platform/integrations-catalog.webp) </Frame> ## Le catalogue La page a deux onglets — **Connectées** montre ce que l’org utilise déjà, **Toutes les intégrations** le catalogue complet avec un champ de recherche. La description de chaque carte est la ligne honnête de ce que la connexion t’apporte : | Intégration | Ce qu’elle fait | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Confluence** | Importer des pages Confluence Cloud dans la base de connaissances de Tale. | | **Discord** | Poster des messages et gérer des canaux dans ton serveur Discord. | | **GitHub** | Gérer des dépôts, des tickets et des pull requests sur GitHub. | | **Gmail** | Lire, envoyer et organiser les e-mails dans Gmail. | | **Google Drive** | Importer des fichiers depuis Google Drive dans la base de connaissances de Tale. | | **IMAP / SMTP Mailbox** | Connecter un serveur mail IMAP + SMTP privé à la Boîte de réception — sans compte Gmail ni Outlook ; l’envoi peut passer par un relais SMTP séparé (Resend, SendGrid, Amazon SES, …) plutôt que par le login de la boîte. | | **Microsoft Outlook** | Gérer le courrier, le calendrier et les contacts Outlook. | | **Shopify** | Synchroniser les produits, les clients et les commandes depuis ta boutique Shopify. | | **Slack** | Envoyer des messages et interagir avec les canaux dans Slack. | | **Tavily** | Recherche web en temps réel et extraction de pages pour la recherche IA. | | **Microsoft Teams** | Envoyer des messages et gérer des canaux dans Microsoft Teams. | | **Twilio** | Envoyer des SMS et passer des appels vocaux avec Twilio. | ## En connecter une Clique sur **Connecter** sur une carte. Les services adossés à OAuth déroulent le flux de consentement du fournisseur ; ceux à token demandent l’identifiant dans une section **Authentification**. La vue de détail liste aussi les opérations de l’intégration — celles badgées **Nécessite une approbation** tiennent dans le chat jusqu’à ce qu’une personne signe, ce qui garde les écritures sortantes sous contrôle ([Configurer les approbations](/fr/platform/approvals/configure)). Les documents importés via Confluence ou Google Drive passent par le même pipeline d’indexation que les téléversements directs, et les citations pointent vers la source — voir [Documents](/fr/platform/knowledge/documents). ## Étendre au-delà du catalogue **Ajouter une intégration** téléverse un connecteur personnalisé — un petit paquet fait d’un `config.json`, d’un `connector.js` ou `.ts` et d’une icône (en `.zip` ou en fichiers séparés, 1 Mo au total). L’aperçu montre ses opérations, ses hôtes autorisés et le code du connecteur avant l’installation, et le résultat apparaît dans le catalogue comme n’importe quelle entrée livrée. Quand aucun connecteur ne convient et que tu peux héberger le pont toi-même, enregistre plutôt un [serveur MCP](/fr/platform/integrations/mcp-servers) — une surface de protocole générique plutôt qu’un connecteur propre à un fournisseur. <Note> WebDAV n’est pas dans ce catalogue parce qu’il pointe dans l’autre sens : il sert les documents de Tale à tes appareils comme un lecteur réseau. Voir [WebDAV](/fr/platform/integrations/webdav). </Note> ## Où cela s’inscrit Les intégrations sont la façon dont les agents agissent sur le monde hors de Tale. Pour l’auteur d’agents, [Outils d’agent](/fr/platform/agents/tools) montre comment les opérations d’une intégration font surface comme outils ; pour l’approbateur, [Configurer les approbations](/fr/platform/approvals/configure) est là où les opérations d’écriture sont retenues ; pour le bâtisseur sans connecteur sous la main, les [serveurs MCP](/fr/platform/integrations/mcp-servers) sont l’alternative ouverte. # Serveurs MCP Source: https://tale.dev/docs/fr/platform/integrations/mcp-servers Un serveur MCP est un processus externe qui expose des outils aux agents de Tale via le Model Context Protocol. Là où une [intégration](/fr/platform/integrations/overview) est un connecteur propre à un fournisseur que Tale livre, un serveur MCP est un pont générique que n’importe qui peut héberger — une API interne, un fournisseur sans connecteur, un script qui calcule ce que les outils intégrés de Tale ne savent pas calculer. Tu héberges le serveur ; Tale ne fait que lui parler. <Frame caption="Le formulaire Ajouter un serveur MCP — une connexion et une méthode d’authentification sont tout l’enregistrement."> ![La boîte de dialogue Ajouter un serveur MCP sous Paramètres API MCP, remplie pour un serveur de tickets de support — nom d’affichage Support Tickets, une description d’une ligne, Streamable HTTP comme type de transport, l’URL du serveur et Aucune comme méthode d’authentification — par-dessus la page MCP, où un serveur Internal Wiki est déjà enregistré.](/images/platform/settings-mcp-add-dialog.webp) </Frame> ## Enregistrer un serveur Ouvre **Paramètres > API > MCP** et clique sur **Ajouter un serveur MCP**. Le formulaire prend : - **Nom** et **Nom d'affichage** — l’identifiant, et le libellé que les agents et les cartes d’approbation affichent. - **Type de transport** — **Streamable HTTP**, **SSE** ou **stdio**. Les transports HTTP prennent une **URL** — le formulaire signale une URL malformée en ligne avant que tu puisses enregistrer ; stdio prend la commande que Tale lance. - **Authentification** — **Aucune**, **Clé API** ou **OAuth 2.0** (URL du jeton, ID client et secret, portées). - **Agents autorisés** — quels agents peuvent se lier à ce serveur. Le défaut est aucun agent ; va vers **Tous les agents** seulement quand le serveur est assez générique pour que chaque agent en bénéficie. **Enregistrer le serveur**, puis utilise **Tester la connexion** sur la ligne pour vérifier la poignée de main — le statut de la ligne affiche **Connecté**, **Déconnecté** ou **Erreur** avec le message amont. ## Les outils découverts Une fois connecté, Tale récupère le manifeste du serveur et le liste comme **Outils découverts** — le nom de chaque outil, sa description et si le serveur le marque **Nécessite une approbation**. Les outils marqués demandent dans le chat chaque fois qu’un agent les appelle, avec les arguments exacts affichés sur la carte ; les outils non marqués s’exécutent comme n’importe quel outil intégré. <Warning> Chaque outil MCP élargit ce que tes agents peuvent atteindre, et les drapeaux d’approbation viennent de l’auteur du serveur — connecter un serveur, c’est accepter son contrat d’outils. Lis la liste découverte avant de pointer des agents vers un serveur que tu n’as pas écrit. </Warning> ## L’utiliser depuis les agents Les outils d’un serveur enregistré et actif rejoignent la panoplie que les agents peuvent appeler ; la requête voyage à travers Tale jusqu’à ton serveur et la réponse revient dans la conversation. Le serveur peut aussi exposer des ressources et des prompts là où son auteur les implémente — les outils sont la surface commune. ## Désactiver et supprimer Chaque ligne de serveur peut être désactivée — ses outils sortent des panoplies d’agents jusqu’à ce que tu le réactives, l’enregistrement étant conservé. Supprimer le serveur retire l’enregistrement entièrement après une confirmation ; le rajouter plus tard est un enregistrement neuf avec une récupération neuve du manifeste. ## Serveur MCP ou intégration Les deux laissent un agent atteindre au-delà de Tale ; la différence est qui possède le connecteur. Les intégrations sont propres à un fournisseur, livrées et entretenues dans le catalogue ; les serveurs MCP sont génériques et à toi de les faire tourner. Va vers l’intégration quand il en existe une pour le système cible ; va vers MCP quand le pont doit être ton propre code. ## Où cela s’inscrit MCP est la surface d’extension ouverte de la panoplie d’agent. Les lectures suivantes naturelles sont [Outils d’agent](/fr/platform/agents/tools) pour la façon dont les outils font surface sur un agent, [Configurer les approbations](/fr/platform/approvals/configure) pour les drapeaux qui retiennent les appels risqués, et le tutoriel [Serveur MCP en partant de zéro](/fr/tutorials/developer/mcp-server-from-scratch) pour en construire un de bout en bout. # WebDAV Source: https://tale.dev/docs/fr/platform/integrations/webdav WebDAV transforme le magasin de documents de Tale en un dossier distant que tu montes comme n’importe quel lecteur réseau partagé. Le magasin sous-jacent est le même que celui que montre le hub documentaire — ce que tu déposes dans le dossier monté apparaît dans l’interface, et inversement. Tout ce qu’il te faut tient sur un panneau : **Paramètres > API > WebDAV** porte les détails de connexion et le générateur de mots de passe applicatifs. <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."> ![La page des paramètres WebDAV montrant une URL de connexion, un champ de nom d’utilisateur avec l’e-mail du compte, une explication indiquant que le mot de passe est un mot de passe applicatif généré, et un tableau de mots de passe applicatifs qui tient deux entrées — Design workstation et MacBook Pro, chacune avec son seul préfixe et sa date de création — à côté d’un bouton Générer.](/images/platform/settings-webdav.webp) </Frame> ## Générer un mot de passe applicatif Le point de terminaison s’authentifie avec des mots de passe applicatifs — de courts secrets que tu frappes par appareil — parce que chaque client WebDAV stocke son identifiant dans le trousseau du système, et qu’un secret cadré et révocable y a sa place, pas le mot de passe de ton compte. Le mot de passe de ton compte ne fonctionne pas sur ce point de terminaison. Clique sur **Générer**, étiquette le mot de passe d’après l’appareil (`MacBook Finder`, `ops-laptop rclone`) et copie-le — un par appareil ; le mot de passe complet ne s’affiche qu’une seule fois. Ensuite le tableau ne garde que le libellé et un court préfixe, assez pour reconnaître la ligne quand tu la révoques. Générer exige la même capacité que celle qui garde les clés API ; les simples Membres demandent à un admin. Pour le nom d’utilisateur, utilise l’e-mail de ton compte Tale. Seul le mot de passe est réellement vérifié, mais l’e-mail garde les lignes d’audit lisibles et correspond à ce que les boîtes de dialogue des clients attendent. ## Se connecter depuis ton appareil L’adresse est l’URL du panneau — `https://<your-site>/dav/<orgSlug>/documents/`. <Tabs> <Tab title="Finder macOS"> Appuie sur **⌘K** (Se connecter au serveur), colle l’URL et connecte-toi avec ton e-mail et le mot de passe applicatif. Le partage se monte dans la barre latérale ; glisse des fichiers dedans pour téléverser, dehors pour télécharger, et renomme ou supprime sur place. Le premier listage d’une grande arborescence peut prendre quelques secondes. </Tab> <Tab title="Windows"> Dans **Ce PC**, choisis **Connecter un lecteur réseau**, colle l’URL comme dossier et coche **Se connecter à l’aide d’informations d’identification différentes**. Windows plafonne les transferts WebDAV à 50 Mo par fichier par défaut — augmente `FileSizeLimitInBytes` sous la clé de registre `WebClient\Parameters` et redémarre le service WebClient. Sur un port HTTPS non standard, règle `BasicAuthLevel` à `2` sous la même clé. </Tab> <Tab title="Fichiers iOS"> Touche le menu à trois points, choisis **Se connecter au serveur** et saisis la même URL et les mêmes identifiants. Fichiers prend en charge la navigation et le téléchargement ; la modification sur place fonctionne pour les formats dotés d’une app iOS. </Tab> <Tab title="rclone"> ```bash rclone config create tale webdav \ url=https://<your-site>/dav/<orgSlug>/documents/ \ vendor=other \ user=<your-email> \ pass=$(rclone obscure '<app-password>') rclone copy ./local-folder tale: --progress ``` `vendor=other` est correct — le serveur de Tale est générique, pas une saveur nommée que rclone reconnaît. </Tab> </Tabs> ## Ce que le montage sait faire Les lectures et écritures reflètent tes permissions du hub documentaire, les fichiers que tu téléverses s’indexent et se recherchent comme des téléversements directs, et leur champ source est réglé sur `webdav` pour le filtrage dans les vues d’audit. Les fichiers de projet font exception : l’onglet **Connaissances** d’un projet est scopé à ce seul projet et n’apparaît jamais via WebDAV, le montage ne montre donc que le hub documentaire de l’organisation. L’espace `.trash/` liste les documents supprimés de façon réversible, en lecture seule — télécharge pour récupérer, restaure via l’interface. Les éditeurs qui prennent des verrous WebDAV (Office, LibreOffice) les obtiennent ; une écriture concurrente pendant une modification renvoie `423 Locked`. ## Révoquer Révoque un mot de passe avec l’icône corbeille de sa ligne — la requête suivante qui le porte est rejetée, les autres appareils ne sont pas touchés, et les verrous qu’il tenait sont libérés. Il n’y a pas d’annulation ; frappe un nouveau mot de passe si tu révoques la mauvaise ligne. <Warning> L’authentification Basic envoie le mot de passe applicatif à chaque requête. Ne monte qu’en HTTPS, garde le mot de passe dans le trousseau du système et ne le colle jamais dans une URL `https://user:pass@host/` — l’historique du shell et les journaux de proxy survivent au montage. Révoque immédiatement au moindre soupçon de fuite. </Warning> ## Où cela s’inscrit WebDAV est la porte par utilisateur, côté appareil, vers les mêmes données que le [hub documentaire](/fr/platform/knowledge/documents) ; le protocole réseau vit sous [API WebDAV](/fr/develop/webdav-api). Pour les imports machine à machine, les [clés API](/fr/platform/admin/api-keys) plus l’API REST sont en général le meilleur choix. # Admin Source: https://tale.dev/docs/fr/platform/admin/overview Admin est le plan de configuration de Tale. Cela couvre les personnes qui peuvent se connecter, les équipes qui les regroupent, les fournisseurs IA derrière chaque réponse, les clés API qui permettent à du code externe de parler à l’organisation, les intégrations tierces que les agents traversent, et le branding que le reste de l’organisation voit. Seuls les Administrateurs et Propriétaires voient le menu Admin complet ; les Développeurs en voient un sous-ensemble, et les autres rôles ne le voient pas du tout. Ces pages décrivent ce que fait chaque réglage et ce qu’il change au produit en cours. La plupart se lisent une fois au montage, puis se revisitent quand quelque chose change — un nouveau collègue, une clé rotée, un nouveau fournisseur. L’histoire des rôles et permissions derrière tout le menu vit dans [Membres et rôles](/fr/platform/admin/members-and-roles) ; commence par là, car chaque autre page Admin renvoie aux noms de rôles qu’elle définit. ## Domaines de configuration <CardGroup cols="2"> <Card title="Membres et rôles" icon="users" href="/fr/platform/admin/members-and-roles"> Les six rôles et la matrice au niveau ressource qui dit qui peut lire, écrire, configurer et gouverner. </Card> <Card title="Équipes" icon="users-round" href="/fr/platform/admin/teams"> Regroupe les membres en équipes qui partagent agents, prompts et intégrations. </Card> <Card title="Agents" icon="bot" href="/fr/platform/admin/agents"> Chaque agent de l’organisation, et là où un Administrateur intervient quand l’un a besoin de gouvernance. </Card> <Card title="Fournisseurs IA" icon="cpu" href="/fr/platform/admin/providers"> Connecte les fournisseurs compatibles OpenAI derrière chaque réponse et choisis quels modèles l’organisation peut utiliser. </Card> <Card title="Sources de jetons" icon="key-round" href="/fr/platform/admin/token-sources"> Des identifiants partagés dont les agents et les outils se servent sans que chaque membre détienne le secret. </Card> <Card title="Intégrations" icon="plug" href="/fr/platform/admin/integrations"> Installe et fais tourner les identifiants derrière Slack, Gmail, Outlook, Google Drive, GitHub, Shopify et plus. </Card> <Card title="Enterprise SSO" icon="shield-check" href="/fr/platform/admin/enterprise-sso"> Branche la connexion à ton fournisseur d’identité via SAML ou OIDC. </Card> <Card title="Clés API" icon="key" href="/fr/platform/admin/api-keys"> Émets et cadre les clés que le code externe utilise pour joindre l’API REST de Tale. </Card> <Card title="Branding" icon="palette" href="/fr/platform/admin/branding"> Le nom, le logo et les couleurs que le reste de l’organisation voit. </Card> <Card title="Authentification à deux facteurs" icon="smartphone" href="/fr/platform/admin/two-factor-authentication"> Exige un second facteur à la connexion et gère l’enrôlement dans toute l’organisation. </Card> <Card title="Changelog" icon="history" href="/fr/platform/admin/changelog"> Le journal in-produit de ce qui a été livré et quand. </Card> <Card title="Gouvernance" icon="scale" href="/fr/platform/admin/governance/audit-logs"> Journaux d’audit, politiques et limites, garde-fous, analyses, rétention et legal hold. </Card> </CardGroup> ## Où cela s’inscrit Admin est la surface que suppose chaque autre onglet. Chat résout un modèle via les fournisseurs configurés ici ; les agents appellent des outils via les intégrations configurées ici ; la bibliothèque de prompts et l’inbox respectent les frontières d’équipe configurées ici. La lecture naturelle en premier est [Membres et rôles](/fr/platform/admin/members-and-roles) — chaque autre page Admin renvoie aux noms de rôles qu’elle définit. # Changelog Source: https://tale.dev/docs/fr/platform/admin/changelog Le changelog est le visualiseur in-produit qui montre les notes de version pour la plateforme Tale elle-même — pas pour le contenu que tes membres produisent. Après une mise à jour auto-hébergée ou un déploiement en cloud géré, le visualiseur liste ce qui a changé entre la version précédente et celle qui tourne maintenant. Les Administrateurs le lisent après une mise à jour pour briefer l'équipe et signaler tout ce qui affecte le travail des membres. Le visualiseur lit les notes de version depuis le dépôt Tale sur GitHub et les met en cache dans ton instance pour que la page charge même quand GitHub est injoignable. ## Où vit le changelog Le changelog a deux surfaces. La page **Quoi de neuf** sous **Aide** liste chaque release récente avec ses notes complètes. Le **toast de mise à jour** se déclenche une fois par saut de version majeure et renvoie directement à la page — le toast montre `Mis à jour vers v<version>` et reste jusqu'à fermeture pour qu'un membre absent ne manque pas l'info. Ouvre la page depuis le menu d'aide dans la barre supérieure, ou depuis le toast de mise à jour quand il apparaît. La page met en cache environ trente releases récentes ; les plus anciennes renvoient vers l'historique des releases GitHub. ## Ce que chaque entrée montre Chaque entrée de release porte quatre champs : le tag de version, la date de publication, le nom de la release (souvent un titre court) et le corps de la release en Markdown. Tale rend le corps comme GitHub — titres, listes, liens et blocs de code survivent tous. Les releases que GitHub n'a pas encore publiées affichent une courte carte explicative avec un lien vers l'historique public des releases. ## Portée Le changelog est le changelog de la plateforme — ce qui a changé dans Tale lui-même. Il ne montre pas les changements à tes agents, à tes workflows ou à ta base de connaissances ; ceux-là ont leur propre historique par ressource. Si tu cherches l'historique de version d'un agent ou d'un workflow, ouvre la ressource et passe à l'onglet **Historique**. Le visualiseur est en lecture seule et visible pour chaque membre connecté. Il n'y a pas de flag Admin-seul — quiconque a un compte peut ouvrir la page. Les données que le visualiseur récupère sont des informations publiques de release du dépôt GitHub Tale, donc il n'y a rien de portée-org à cacher. ## Une mise à jour mise en pratique Après une mise à jour auto-hébergée de `v0.42` à `v0.45`, connecte-toi et cherche le toast de mise à jour en haut à droite. Clique sur **Voir** pour ouvrir la page changelog. La page montre trois entrées de release (`v0.43`, `v0.44`, `v0.45`), les plus récentes en premier, chacune avec les notes écrites par les ingénieurs depuis la release GitHub. Parcours les points saillants, partage le lien avec l'équipe si quelque chose mérite un public plus large, et le toast s'efface au prochain rechargement. Quand la mise à jour dépasse la fenêtre cachée, la page montre les entrées les plus récentes avec une bannière qui renvoie à GitHub pour les notes plus anciennes. Le cache reste chaud pour le prochain lecteur sur ton instance. ## Où ça s'inscrit Le changelog est la lecture opérateur de ce que Tale lui-même vient de faire ; il se tient à côté du journal d'audit (qui enregistre ce que tes membres ont fait) et de la page fournisseurs (qui suit quelles versions de modèles sont câblées). Combine-le avec [mise à jour auto-hébergée](/fr/self-hosted/operate/upgrades) quand tu opères l'instance — le guide de mise à jour parcourt le saut de version, et le changelog en lit le résultat de l'autre côté. # Branding Source: https://tale.dev/docs/fr/platform/admin/branding Le branding est la surface qui échange le chrome par défaut de Tale contre celui de ton organisation. La page couvre les assets que la plateforme habille — logo, favicon et la couleur d’accentuation dont dérive la palette — et explique où chacun apparaît pour que tu aies un aperçu avant d’enregistrer. Le nom du produit lui-même suit automatiquement le nom de ton organisation, il n’y a donc pas de champ séparé à remplir. Les Administrateurs vont vers le branding quand une instance auto-hébergée s’expose à un public externe ou quand un déploiement interne doit sembler natif à l’entreprise. Seuls les Administrateurs et Propriétaires peuvent éditer le branding. Tous les autres voient le résultat ; le formulaire lui-même est caché aux Éditeurs, Développeurs et Membres. <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.](/images/platform/settings-branding.webp) </Frame> ## Où vit le branding Ouvre **Paramètres > Branding**. Le formulaire a trois sections (téléversement du logo, téléversement du favicon, couleur d’accentuation) et un aperçu en direct qui reflète la barre latérale avec les valeurs que tu édites. Enregistrer applique le changement pour chaque membre de _cette_ organisation à son prochain chargement de page — il n’y a pas de surcharge par utilisateur. Le branding est limité à une organisation. Chaque organisation conserve son propre logo, favicon et sa couleur d’accentuation, donc changer d’organisation bascule le chrome vers le branding de cette organisation au lieu de garder celui de la précédente. Éditer ici ne change que l’organisation dans laquelle tu te trouves actuellement. ## Le nom du produit Il n’y a pas de champ « nom d’app » ni « logo texte ». La marque de mot dans l’en-tête de la barre latérale et le nom dans le titre d’onglet du navigateur sont le nom propre de ton organisation, que tu définis sur la page **Paramètres > Organisation**. Renomme l’organisation et le chrome suit au prochain chargement de page. Téléverse une image de logo (ci-dessous) et elle prend la place de la marque de mot ; sans logo, le nom de l’organisation est rendu comme marque de mot textuelle. ## Les assets **Logo** est une image — PNG, SVG ou JPG. La plateforme la rend à la hauteur de la barre latérale ; vise un fond transparent et une marque de mot lisible à environ 32 pixels de haut. Le logo est un téléversement unique utilisé sur les deux thèmes — choisis une marque lisible sur fond clair comme sombre. Sans logo, le chrome retombe sur le nom de ton organisation comme marque de mot textuelle. **Favicon** est l’icône d’onglet. Téléverse une variante claire et une variante sombre pour que l’icône reste lisible quel que soit le thème choisi par le système d’exploitation — ou laisse-le vide, et Tale en dérive un de ton logo dès que tu le téléverses, si bien qu’un seul téléversement habille à la fois la barre latérale et l’onglet du navigateur. Un favicon explicite l’emporte toujours sur celui dérivé automatiquement. **Couleur d'accentuation** est la seule couleur dont dérive la palette de marque — boutons, anneaux de focus, états de sélection et la ligne active de la barre latérale en tirent tous leur ton. Elle accepte toute valeur hex, choisie une fois pour les modes clair et sombre ; Tale dérive une palette lisible par thème — une couleur difficile à lire contre le fond d’un thème est poussée vers le contraste pour ce thème seulement, l’autre reste intact, et la même marque se lit proprement sur les deux. L’aperçu reflète la palette dérivée pour le thème que tu regardes actuellement. ## Un rebranding mis en pratique Pour rebrander une instance pour `Acme Corp`, mets d’abord le nom de l’organisation à `Acme Corp` sur la page **Paramètres > Organisation** — ce nom devient la marque de mot de la barre latérale et le titre d’onglet du navigateur. Ouvre ensuite **Paramètres > Branding**, téléverse la marque de mot de l’entreprise comme logo, et colle le hex de marque (`#3B82F6` dans l’exemple) dans le champ de couleur d’accentuation. Laisse le favicon vide, et Tale en génère un depuis le logo. Le panneau d’aperçu à droite se met à jour pendant que tu tapes. Enregistrer applique le changement ; la barre latérale, l’onglet du navigateur et le favicon reflètent le nouveau branding immédiatement. ## L’écran de connexion personnalisé Les écrans de connexion, d’inscription et de réinitialisation de mot de passe s’affichent avant que tu aies choisi une organisation — il n’y a donc aucune organisation dans le contexte pour les brander. Ils montrent le branding par défaut de la plateforme plutôt que celui d’une organisation précise ; le branding par organisation prend le relais dès que tu arrives dans l’espace de travail de cette organisation. Déconnecte-toi et recharge l’URL de connexion pour vérifier quels assets utilisent les écrans pré-authentification. ## Où ça s’inscrit Le branding est la couche visuelle au-dessus de toute autre surface admin ; SSO, courriels et journaux d’audit portent le chrome brandé jusqu’à tes membres. Comme le nom du produit est le nom propre de l’organisation, garde-le net dans [membres et rôles](/fr/platform/admin/members-and-roles). Combine le branding avec [fournisseurs](/fr/platform/admin/providers) pour que les noms de modèles dans l’en-tête de chat correspondent au chrome qui les entoure, et avec [membres et rôles](/fr/platform/admin/members-and-roles) pour que les personnes qui peuvent éditer le branding soient les mêmes qui détiennent le reste du chrome de l’org. # Politiques et limites Source: https://tale.dev/docs/fr/platform/admin/governance/policies-and-limits Politiques et limites est la surface où tu plafonnes ce que tes membres et agents peuvent consommer. Les budgets plafonnent les tokens, le coût et les requêtes par période de facturation ; les contrôles de fonctionnalité activent la recherche web, l’exécution de code et l’upload de fichiers par scope ; la politique d’upload régit les types et tailles de fichiers qu’un membre peut joindre ; la politique de rétention décide combien de temps chaque type de donnée vit avant le nettoyage. Les Administrateurs et Propriétaires lisent cette page quand une charge dépasse le budget, quand une fonctionnalité doit être coupée pour un sous-ensemble d’utilisateurs, ou quand un régulateur nomme une fenêtre de rétention différente du défaut. <Frame caption="Gouvernance > Politiques et limites — le tableau des règles de budget, au-dessus de la politique d’upload 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 developer, chacune plafonnant les tokens, le coût et les requêtes — au-dessus des champs de politique d’upload pour les types de fichiers autorisés, les tailles et le volume.](/images/platform/governance-policies-limits.webp) </Frame> ## Un budget mis en pratique Pour plafonner la dépense mensuelle d’un Éditeur, ouvre **Paramètres > Gouvernance > Budgets** et clique sur **Ajouter une règle**. Choisis **Rôle** comme scope, **Éditeur** comme cible, règle la période sur **Mensuel** et entre un coût max en USD. Enregistre et la prochaine requête de mois-période qui pousserait un Éditeur au-delà du plafond est refusée avec une erreur budget-dépassé. Un seuil d’avertissement sous le plafond déclenche une alerte avant que le plafond ne soit atteint. Les scopes plus étroits l’emportent sur les plus larges — une règle utilisateur bat une règle équipe bat une règle rôle — et les limites au niveau org s’appliquent toujours par-dessus comme plafond additionnel. ## Les quatre couches de politique **Budgets** sont des plafonds de tokens, coût et requêtes par scope et période. Les scopes sont org, rôle, équipe, utilisateur ou clé API. Chaque règle porte un plafond de tokens, un plafond de coût en USD, un plafond de requêtes optionnel et un seuil d’avertissement exprimé en pourcentage du plafond. Une règle sur clé API vise une seule clé émise (choisis **Clé API** comme scope, puis la clé depuis **Paramètres > API**) et ne plafonne que le trafic authentifié avec cette clé — l’API REST et compatible OpenAI — pour que tu mesures une intégration précise sans toucher à l’usage in-app. La génération d’images est mesurée par coût et nombre de requêtes, pas par tokens — une requête d’image ne rapporte aucun token, alors plafonne les dépenses d’images avec le plafond de coût ou de requêtes, pas celui de tokens. **Contrôles de fonctionnalité** activent la recherche web, l’exécution de code et l’upload de fichiers par scope, et plafonnent les tokens de contexte max pour les réponses AI. Une fonctionnalité coupée pour un scope cache la bascule dans le chat et refuse la requête côté serveur. **Politique d'upload** régit les extensions de fichiers, types MIME et tailles qu’un membre peut joindre. Elle plafonne aussi le volume total par utilisateur — utile quand le stockage est mesuré. Désactive la politique pour un défaut permissif ; active-la pour appliquer les listes. **Politique de rétention** décide combien de temps chaque type de donnée (historique de chat, documents, prompts, journaux d’audit, registre d’utilisation, exécutions de workflow et plus) reste avant que la passe de nettoyage ne retire la ligne. La page affiche les bornes imposées par l’opérateur, la surcharge par organisation dans ces bornes, et une fenêtre de grâce avant la suppression dure. ## Priorité Les quatre couches partagent la même échelle de scope : utilisateur > équipe > rôle > org > défaut. La règle la plus étroite l’emporte. Là où une couche porte un plafond au niveau org (budgets), le plafond s’applique comme plafond additionnel au-dessus de toute règle plus étroite. Un budget sur clé API sort de l’échelle comme son propre bucket indépendant : il lie le trafic de la clé elle-même, indépendamment des plafonds utilisateur, équipe ou org de son propriétaire, si bien qu’une seule clé peut être tenue à une allocation plus serrée que la personne qui l’a émise. ## Bornes de rétention et approbations La politique de rétention vit à l’intérieur de bornes imposées par l’opérateur — l’opérateur en self-hosted règle un plancher et un plafond par catégorie, et la valeur de l’organisation se clampe à cette plage. Quand l’opérateur propose un plancher plus serré ou un plafond plus bas, le changement remonte comme proposition que les Administrateurs peuvent appliquer ou rejeter. Les réductions de la politique atterrissent avec un bandeau de changement en attente et une fenêtre de grâce avant prise d’effet — la même grâce donne aux Administrateurs la chance d’annuler. ## Délai d’inactivité de session Le délai d’inactivité de session déconnecte les membres après une période d’inactivité — le contrôle lié aux sessions que les référentiels de conformité demandent (SOC 2 CC6.1). Ouvre **Paramètres > Gouvernance > Sécurité et surveillance**, active **Activer le délai d'inactivité de session** et règle **Délai d'inactivité (minutes)** (1–1440, 30 par défaut). Les membres voient un avertissement peu avant la coupure ; ensuite l’onglet actif se déconnecte et la page de connexion explique la déconnexion au lieu d’afficher un simple formulaire. La fenêtre peut uniquement raccourcir la limite définie pour le déploiement, jamais l’allonger. Les opérateurs en self-hosted règlent ce plafond dur par variable d’environnement (voir la [référence d’environnement](/fr/self-hosted/configuration/environment-reference)) ; la politique d’organisation s’applique par-dessus, et la plus stricte des deux fenêtres l’emporte. Un membre de plusieurs organisations reçoit la fenêtre la plus stricte de toutes ses organisations. L’application a deux moitiés. Le watchdog côté navigateur termine à la minute près les sessions ouvertes et visibles. Les onglets fermés et les appareils abandonnés sont rattrapés côté serveur par une passe de révocation qui tourne environ toutes les cinq minutes — une session peut donc survivre quelques minutes au-delà de la fenêtre ; quand tu présentes le contrôle à un auditeur, compte la fenêtre plus une demi-heure environ dans le pire cas. Chaque révocation côté serveur atterrit dans les [journaux d’audit](/fr/platform/admin/governance/audit-logs) comme `session.idle_revoked`. Une réserve pour les déploiements trusted headers : le reverse proxy y possède l’authentification, donc une session révoquée se rétablit dès que le membre confirme l’avis de connexion — associe la politique à un délai d’inactivité côté proxy ou IdP pour un vrai verrouillage. ## Où cela s’inscrit Politiques et limites est la couche budget et porte qui protège l’organisation des dépenses qui s’emballent et des accès non voulus. Associe-la à [contenu et modèles](/fr/platform/admin/governance/content-models), pour que le modèle plafonné par budget soit aussi celui que la liste d’accès autorise, et à [politique de rétention sur la même page](#bornes-de-retention-et-approbations), pour que les données que l’organisation garde soient aussi bornées. La page compagnon est [journaux d’audit](/fr/platform/admin/governance/audit-logs) — chaque changement de politique ici y atterrit comme enregistrement permanent. # Politique run-code Source: https://tale.dev/docs/fr/platform/admin/governance/run-code-policy Politique run-code est la surface où tu décides quels paquets Python et Node la sandbox peut installer à l’exécution. Les skills avec scripts et l’outil Run code tournent tous deux dans la même sandbox ; cette politique est la couture unique où tu serres ou desserres ce qu’ils peuvent installer. Les Administrateurs et Propriétaires lisent cette page quand un agent a besoin d’une nouvelle bibliothèque, ou quand un audit demande pourquoi un paquet était bloqué à un moment donné. <Frame caption="Gouvernance > Paquets run-code — le groupe d’options du mode par défaut, au-dessus des listes d’autorisation et de blocage Python et Node."> ![La page de gouvernance Politique run-code avec Liste d’autorisation coché dans le groupe d’options du mode par défaut, au-dessus d’une liste d’autorisation Python qui tient pandas, numpy, scipy et scikit-learn, d’une liste de blocage Python qui tient paramiko, fabric, pexpect et scapy, et d’une liste d’autorisation Node qui tient axios, date-fns, dayjs et lodash.](/images/platform/governance-run-code-policy.webp) </Frame> ## Un basculement mis en pratique Le mode par défaut est **Liste de blocage** avec liste vide, ce qui veut dire que tous les paquets sont installables. Pour passer à un ensemble curé, ouvre **Paramètres > Gouvernance > Paquets run-code**, change le mode en **Liste d'autorisation** et énumère les paquets de confiance sous **Liste d'autorisation Python** et **Liste d'autorisation Node**. Enregistre et la prochaine exécution sandbox qui demande un paquet hors de la liste échoue avec la raison **absent de la liste d'autorisation** dans l’événement d’audit. ## Les deux modes | Nom | Par défaut | Description | | -------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Liste d’autorisation | off | Seuls les paquets listés s’installent ; tout le reste est rejeté. À utiliser quand un régulateur nomme les bibliothèques approuvées. | | Liste de blocage | on | Tous les paquets s’installent sauf ceux listés. À utiliser quand un petit ensemble est connu mauvais et que le reste est de confiance. | ## Les quatre listes Chaque mode lit deux listes — Python et Node. Un paquet par ligne, ou séparé par des virgules. Les contraintes de version sont retirées automatiquement (`pandas==2.1` correspond à `pandas`), donc la politique est basée sur le nom et survit aux montées de version des bibliothèques. Les paquets Node scopés (`@scope/pkg`) sont pris en charge. Les listes sont indépendantes par langage : une liste d’autorisation Python plus une liste de blocage Node est une combinaison valide, et veut dire que Python est strict et Node est permissif sur la même sandbox. ## Le testeur Le panneau Test sur la même page permet de coller des spécifications pip ou npm et voir si chacune passerait sous le brouillon courant. Il utilise tes modifications non enregistrées, donc tu peux itérer avant d’enregistrer. Chaque spécification est parsée, dépouillée de sa contrainte de version et confrontée aux listes ; le panneau rapporte **Autorisé** ou **Refusé** avec la raison — correspond-à-la-liste-d’autorisation, absent-de-la-liste-d’autorisation, correspond-à-la-liste-de-blocage, absent-de-la-liste-de-blocage. ## Egress réseau et skills La politique de paquets régit _ce qui_ tourne dans la sandbox. La même sandbox fait tourner les scripts de skill — voir la [page concept Skills](/fr/platform/agents/skills). Le réseau sortant depuis le code sandbox est ouvert par défaut, les métadonnées cloud et les plages privées étant toujours bloquées ; sur les déploiements auto-hébergés, l’opérateur peut le restreindre à une allowlist d’hôtes au niveau du déploiement — la marche à suivre vit dans [Durcissement](/fr/self-hosted/operate/security/hardening). Traite la publication d’un skill avec script comme un élargissement de la surface de confiance pour chaque agent qui l’adopte ; la politique de paquets et la politique d’egress du déploiement décident ensemble ce que le script peut faire. ## Où cela s’inscrit Politique run-code est la porte sur la sandbox qui supporte à la fois l’outil Run code et les scripts de skill. Le concept compagnon est [skills d’agent](/fr/platform/agents/skills) — il couvre quand publier un script comme skill, et pourquoi la politique de paquets est la porte porteuse. La page gouvernance compagnon est [journaux d’audit](/fr/platform/admin/governance/audit-logs) — chaque installation de paquet refusée y atterrit avec la spécification et la raison. # Contenu et modèles Source: https://tale.dev/docs/fr/platform/admin/governance/content-models Contenu et modèles est la surface où tu décides quels LLMs les personnes de ton organisation peuvent atteindre et celui sur lequel chaque groupe atterrit par défaut. Elle associe une liste d’autorisation ou de blocage par scope (organisation, équipe, rôle, utilisateur) à une règle de modèle par défaut que le résolveur applique quand aucun agent ni aucune conversation n’a outrepassé le choix. Les Administrateurs et Propriétaires lisent cette page quand une règle de conformité épingle une charge à un modèle approuvé, quand une équipe doit avoir un modèle par défaut moins cher que le reste de l’organisation, ou quand un nouveau modèle d’un fournisseur existant doit être rendu joignable. <Frame caption="Gouvernance > Contenu et modèles — le préfixe et le suffixe de prompt système obligatoires, au-dessus des règles de modèle par défaut par scope."> ![La page de gouvernance Contenu et modèles montrant les champs de préfixe et de suffixe de prompt système obligatoires remplis des règles maison de l’organisation, au-dessus d’un tableau de modèles par défaut qui porte trois règles — un défaut pour tous les utilisateurs et une règle de rôle pour Développeur et pour Membre, chacune épinglée à un modèle OpenRouter.](/images/platform/governance-content-models.webp) </Frame> ## Un défaut mis en pratique Pour régler le modèle par défaut du rôle Éditeur, ouvre **Paramètres > Gouvernance > Default Models** et clique sur **Ajouter une règle**. Choisis **Rôle** comme scope, **Éditeur** comme cible, puis choisis le fournisseur et le modèle. Enregistre et la prochaine requête d’un Éditeur sans surcharge explicite par agent ou par conversation atterrit sur le modèle de la règle. Les scopes plus étroits l’emportent — une règle utilisateur bat une règle équipe bat une règle rôle bat le défaut org. ## Les deux couches **Accès au modèle** est la liste d’autorisation ou de blocage qui régit quels modèles un scope peut utiliser tout court. Un modèle absent de la liste d’autorisation est invisible pour ce scope — le sélecteur le cache et le résolveur refuse de s’y lier, même si un agent l’a épinglé. Va vers la liste d’autorisation quand un régulateur nomme les modèles approuvés ; va vers la liste de blocage quand un seul modèle doit être hors-limites partout ailleurs. **Modèles par défaut** est la règle du résolveur qui choisit le modèle quand rien d’autre ne l’a fait — pas de surcharge par agent, pas de surcharge par conversation. Le défaut s’applique au moment où l’utilisateur lance un chat frais et s’applique en repli quand le modèle épinglé d’un agent n’est pas joignable. ## Scopes et priorité Les deux couches portent un scope : organisation, équipe, rôle ou utilisateur. Le résolveur évalue du plus étroit au plus large — utilisateur l’emporte sur équipe sur rôle sur défaut org. La couche d’accès au modèle se combine avec la couche de modèle par défaut ; le défaut que le résolveur choisit doit aussi passer le contrôle d’accès du même scope, sinon le résolveur se replie sur le modèle autorisé le plus proche. ## Avertissements liste d’autorisation et liste de blocage L’éditeur de modèles par défaut affiche un avertissement quand une règle nomme un modèle que la liste d’autorisation du même scope n’autorise pas, ou quand la liste de blocage du même scope le bloque. L’avertissement n’empêche pas d’enregistrer — le résolveur se repliera à la requête — mais il signale l’incohérence pour que tu corriges l’une ou l’autre. ## Où cela s’inscrit Contenu et modèles est la porte que chaque chat et chaque agent franchissent à la requête. Associer accès au modèle et modèles par défaut permet de livrer une posture de conformité serrée sans forcer chaque auteur d’agent à se souvenir du modèle approuvé ce trimestre. La page compagnon est [politiques et limites](/fr/platform/admin/governance/policies-and-limits) — elle couvre les plafonds de coût et de requêtes qui s’appliquent au-dessus des choix de modèle faits ici. # Garde-fous Source: https://tale.dev/docs/fr/platform/admin/governance/guardrails Garde-fous est la surface où tu configures les trois couches de filtres que Tale applique à chaque message de chat dans ton organisation. Chaque message traverse la sécurité du contenu (listes de mots et regex administrateur), puis la détection PII (motifs intégrés plus personnalisés), puis un fournisseur de modération externe optionnel — dans cet ordre fixe, à l’entrée et à la sortie. Les Administrateurs et Propriétaires lisent cette page quand un régulateur nomme une règle de contenu, quand une fuite justifie une politique plus stricte, ou quand les réponses d’un agent doivent être assainies avant de quitter le modèle. <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 — la sécurité du contenu appliquée à l’entrée et à la sortie sur deux catégories, la détection PII en mode mask sur quatre motifs intégrés, et le fournisseur de modération marqué Désactivé, sans API externe configurée — au-dessus du flux des événements récents, qui n’en signale encore aucun.](/images/platform/governance-guardrails.webp) </Frame> ## Un layering mis en pratique Pour configurer les couches, ouvre **Paramètres > Gouvernance > Garde-fous**. L’aperçu affiche trois cartes de statut, une par couche — sécurité du contenu, détection PII, modération. Chaque carte renvoie vers sa propre page de configuration où tu choisis si la couche tourne sur l’entrée, sur la sortie ou les deux, et ce qu’elle fait à un match (bloquer le message, masquer le match, ou marquer et laisser passer). Le tableau des événements récents en bas de l’aperçu affiche les 50 dernières détections, blocages et erreurs fournisseur avec leur couche, leur direction et leur catégorie de match. ## Sécurité du contenu La sécurité du contenu est la couche que tu possèdes toi-même. Définis une ou plusieurs catégories — discours haineux, profanité, une regex personnalisée pour un nom de code interne — et choisis un mode par catégorie : **Bloquer** refuse le message, **Masquer** remplace les matches par un placeholder, **Marquer** consigne la détection sans changer le message. Bloquer l’emporte sur Masquer l’emporte sur Marquer quand plusieurs catégories matchent. Les listes de mots et motifs de cette couche ne quittent jamais le déploiement. Le texte trouvé n’est pas stocké — seule la catégorie, la direction (entrée ou sortie) et le nombre de matches finissent dans l’événement d’audit. ## Détection PII La détection PII embarque des motifs pour les e-mails, téléphones, IDs gouvernementaux, numéros de paiement et une longue traîne de formats régionaux. Ajoute des motifs personnalisés si ton régulateur nomme un format que les motifs intégrés ratent. Choisis un mode — Bloquer, Masquer avec un placeholder, ou Marquer — et une direction d’application. Masquer est le choix typique pour le filtrage de sortie quand le modèle a eu accès à des enregistrements contenant des PII qu’il ne doit pas répéter. ## Fournisseur de modération La couche modération est un classifieur externe — OpenAI Moderation, Azure Content Safety, Perspective API, ou un endpoint HTTP personnalisé. Configure l’endpoint du fournisseur, une clé API et le mapping catégorie-vers-action (chaque fournisseur renvoie sa propre taxonomie ; le mapping décide quelles catégories bloquent, masquent ou marquent). La couche est optionnelle — laisse-la désactivée et seules les deux premières couches tournent. Le fournisseur se trouve sur le chemin d’egress réseau. Les pannes sont configurables par direction : fail-open laisse passer le message, fail-closed le refuse. La vue des événements récents affiche les erreurs fournisseur, les statuts HTTP et les événements circuit-open quand la couche est rate-limited. ## Événements récents Chaque détection, blocage et erreur fournisseur atterrit dans le tableau des événements récents pour 30 jours. Filtre par couche ou par type ; clique sur une ligne pour voir les catégories trouvées, l’acteur, l’identifiant de message et l’horodatage. Le texte brut trouvé n’est jamais stocké — les événements sont une surface de réglage, pas une archive de contenu. ## Où cela s’inscrit Garde-fous est le filtre runtime entre l’utilisateur et le modèle dans les deux sens. Associe-le à [contenu et modèles](/fr/platform/admin/governance/content-models), pour qu’un modèle approuvé soit aussi soumis aux règles de contenu approuvées. La page compagnon est le [journal d’audit](/fr/platform/admin/governance/audit-logs) — chaque blocage et chaque masquage que les couches garde-fous appliquent y atterrit comme enregistrement permanent. # Analyse d'utilisation Source: https://tale.dev/docs/fr/platform/admin/governance/usage-analytics Analyse d'utilisation est le dashboard qui agrège chaque appel AI facturable dans une vue unique de tokens, coût et volume de requêtes. Il découpe par utilisateur, équipe, rôle, modèle, agent et temps, pour que la ligne inattendue sur la facture soit traçable jusqu'à la charge qui l'a portée. Les Administrateurs et Propriétaires lisent cette page quand une facture est inattendue, quand la direction veut la forme approximative des dépenses AI, ou quand une alerte de budget se déclenche et la question suivante est _qui et quoi_. ## Un drill-down mis en pratique Ouvre **Paramètres > Gouvernance > Utilisation**. La vue par défaut sont les 30 derniers jours, org-wide, avec les trois compteurs phares — tokens totaux, coût total en USD, requêtes totales. Bascule la ventilation sur **Par utilisateur** pour trouver les plus gros consommateurs, **Par modèle** pour comparer un primaire coûteux à un repli moins cher, ou **Par agent** pour trouver l'agent qui porte la charge. Chaque ligne renvoie à une série temporelle par ligne ; l'axe du graphique suit la période choisie. ## Les dimensions - **Utilisateur** — chaque membre qui a déclenché un appel facturable. Associe au filtre équipe ou rôle pour cadrer la vue. - **Équipe** — agrégé par membre d'équipe ; utile quand les budgets sont cadrés par équipe. - **Rôle** — Propriétaire, Administrateur, Développeur, Éditeur, Membre. - **Modèle** — chaque modèle qui a produit une réponse, groupé par fournisseur. - **Agent** — chaque agent nommé (le classement trie par volume de tokens, coût ou nombre de requêtes). - **Temps** — tendance quotidienne pour les fenêtres courtes, hebdomadaire pour les fenêtres plus longues. ## Le modèle de coût Le coût est une estimation. Chaque requête atterrit dans le registre d'utilisation avec les tokens d'entrée, les tokens de sortie, le prix publié du modèle par million de tokens et la durée wall-clock. Le dashboard multiplie tokens par prix ; les appels de génération d'images atterrissent avec un coût par image que le fournisseur renvoie. La ligne du registre est la source de vérité, et le [journal d'audit](/fr/platform/admin/governance/audit-logs) porte l'acteur et l'horodatage de la ligne pour le recoupement. ## Superpositions de budget Quand [politiques et limites](/fr/platform/admin/governance/policies-and-limits) a un budget pour un scope, le graphique d'utilisation superpose le plafond comme une ligne horizontale. Survoler un point affiche le pourcentage du plafond consommé et la projection de fin de mois basée sur la tendance courante. Franchir le seuil d'avertissement colore la série en ambre ; franchir le plafond la colore en rouge et fait apparaître les événements budget-dépassé comme marqueurs sur l'axe temps. ## Rétention des lignes d'utilisation Le registre d'utilisation a sa propre fenêtre de rétention dans [politiques et limites](/fr/platform/admin/governance/policies-and-limits). Le défaut est 365 jours ; raccourcis-le et le graphique historique se tronque en conséquence. Le dashboard reflète ce que tient le registre — il n'y a pas de couche d'archive en dessous. ## Où cela s'inscrit Analyse d'utilisation est le côté dépense et volume de la même charge que [analyse des retours](/fr/platform/admin/governance/feedback-analytics) lit pour la qualité. Ensemble elles répondent à _cet agent vaut-il son coût_. La page compagnon est [politiques et limites](/fr/platform/admin/governance/policies-and-limits) — la page où les budgets que ce dashboard superpose sont configurés. # Conservation légale Source: https://tale.dev/docs/fr/platform/admin/governance/legal-hold Conservation légale est le mécanisme que Tale livre pour préserver des preuves sous conservation contentieuse. Un hold épingle une cible — un utilisateur, un document, un thread, une exécution de workflow ou l’organisation entière — hors de portée du balayage de rétention et de la cascade d’effacement des personnes concernées. Les Administrateurs et Propriétaires lisent cette page quand le conseil leur demande de préserver les données d’un custodian, quand une demande de levée a besoin de la signature à double contrôle, ou quand un audit réconcilie quels holds étaient en vigueur à une date donnée. <Frame caption="Gouvernance > Conservation légale — le tableau des holds actifs 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 un hold actif — de type Utilisateur sur marta.vogel, placé 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.](/images/platform/governance-legal-hold.webp) </Frame> ## Une mise en place mise en pratique Pour placer un hold sur un utilisateur, ouvre **Paramètres > Gouvernance > Conservation légale** et clique sur **Placer une conservation légale**. Choisis le type de cible — utilisateur, thread, document, exécution ou organisation — choisis la cible précise, ajoute un motif et lie le hold à un dossier s’il y en a un d’ouvert. Le hold prend effet immédiatement ; les balayages de rétention sautent les lignes de la cible, la cascade d’effacement les rapporte comme **Ignorées par hold**, et la ligne cible porte le badge **Sous conservation légale** dans chaque liste où elle apparaît. ## Les quatre sections **Holds actifs** est la liste de travail de chaque hold actuellement en vigueur. Chaque ligne porte le type, la cible, le motif, le dossier, qui l’a placé et quand. Filtre par type ou par dossier pour cadrer la vue. **Demandes de levée** est la file à double contrôle. Lever un hold demande qu’un autre Administrateur approuve la demande ; les demandes approuvées attendent encore un délai de refroidissement avant de prendre effet. La section se sépare en _en attente d’approbation_ et _approuvée, en attente du refroidissement_, pour que la file et le minuteur soient tous deux visibles. **Dossiers** groupe les holds par affaire. Chaque dossier porte un nom, un numéro de dossier et la liste des holds liés. Fermer un dossier dépose des demandes de levée pour chaque hold lié — toujours soumises à l’approbation à double contrôle par demande. **Historique des levées** est l’audit en lecture seule des levées effectuées et rejetées. Utilise-le pour réconcilier contre une lettre de préservation du conseil adverse ou alimenter un rapport d’audit. ## Interaction hold-et-cascade Un hold bloque chaque passage de rétention et chaque étape d’effacement pour la cible. La page Corbeille affiche le bandeau **La suppression est bloquée par un legal hold actif** quand un Administrateur tente de purger une ligne sous hold. Une demande de personne concernée dont le sujet est couvert par un hold atterrit en statut **Bloquée** jusqu’à ce que le hold soit levé ; une couverture partielle (certains threads sous hold, d’autres pas) atterrit en **Partielle** avec des compteurs par catégorie dans le reçu. ## Double contrôle Placer et lever ne sont pas symétriques. Placer est une action d’un Administrateur seul — la vitesse compte quand un litige arrive. Lever est à double contrôle : l’Administrateur demandeur dépose, un autre Administrateur approuve, et un délai de refroidissement s’applique entre l’approbation et l’effet pour qu’une levée hâtive puisse encore être annulée. Les deux moitiés du workflow sont auditées de bout en bout. ## Où cela s’inscrit Conservation légale est le bouton gel sur la rétention. C’est le seul mécanisme qui bat le balayage chronométré de la rétention et la cascade d’effacement des personnes concernées — les deux respectent les holds par conception. Les pages compagnons sont [demandes des personnes concernées](/fr/platform/admin/governance/data-subject-requests) pour le côté cascade et [politiques et limites](/fr/platform/admin/governance/policies-and-limits) pour les fenêtres de rétention que le hold outrepasse. # Journaux d'audit Source: https://tale.dev/docs/fr/platform/admin/governance/audit-logs Le journal d'audit est l'enregistrement immuable de chaque action conséquente dans ton organisation. Chaque connexion, changement de rôle, modification de fournisseur, sauvegarde d'agent, exécution de workflow et invocation de sandbox y atterrit avec l'acteur, la ressource, l'état avant/après et l'horodatage. Les Administrateurs et Propriétaires lisent ceci quand un audit demande qui a touché une ressource et quand, quand un responsable conformité a besoin d'un export, ou quand quelque chose dérape et la question est _qui a changé quoi à 03:14_. Cette page est la référence pour les colonnes, les filtres, les catégories et les formats d'export. La fenêtre de rétention pour les lignes d'audit se règle dans la même zone Gouvernance sous politique de rétention — garde-la assez longue pour satisfaire tes exigences de conformité avant que les lignes ne soient éliminées. ## Un filtre mis en pratique Pour trouver le moment où le rôle d'un membre a changé, ouvre **Paramètres > Gouvernance > Journaux d'audit**, règle le filtre **Catégorie** sur **Membre** et cherche l'acteur ou la cible par nom. Chaque ligne s'étend en payload complète — état précédent, état nouveau, l'IP si la requête est passée par le réseau, le type d'acteur (utilisateur, système, API, workflow). Exporte la sélection filtrée en CSV ou JSON depuis la barre d'outils au-dessus du tableau. ## Les colonnes | Nom | Type | Requis | Description | | --------------- | -------- | ------ | ---------------------------------------------------------------------------------------------- | | Horodatage | ISO 8601 | oui | Heure serveur à laquelle l'action a été validée. | | Action | string | oui | L'action sémantique — `update_member_role`, `provider_created`, `agent_saved`. | | Utilisateur | string | oui | Nom affiché de l'acteur ; `System`, `API` ou `Workflow` quand l'acteur n'est pas une personne. | | Ressource | string | oui | La ressource touchée par l'action — `agent`, `provider`, `member`, `workflow`. | | Catégorie | enum | oui | Auth, Membre, Données, Intégration, Workflow, Sécurité, Admin, AI, Skill, Agent. | | Statut | enum | oui | Succès, Échec, Refusé. | | Champs modifiés | JSON | non | Le diff entre l'état précédent et le nouveau pour les actions de mise à jour. | ## Filtres Filtre par plage de dates, catégorie, statut, acteur, ressource ou recherche libre sur les noms d'action. Combine les filtres — une plage de dates plus la catégorie **Sécurité** plus le statut **Refusé** fait remonter les tentatives de connexion ratées sur une fenêtre. L'état des filtres se reflète dans l'URL ; un lien sauvegardé rouvre la même vue. ## Exporter Deux formats d'export sont livrés : CSV pour les tableurs et JSON pour les systèmes en aval. Les deux respectent les filtres actifs — ce que tu exportes est ce que tu vois. Définis les filtres voulus (le filtre mis en pratique ci-dessus est le modèle), puis choisis CSV ou JSON dans la barre d'outils au-dessus du tableau. Les exports volumineux se téléchargent en streaming ; la barre d'outils suit la progression et signale la fin avec la taille du fichier et le nombre de lignes. Le CSV arrive sous `audit-logs-<timestamp>.csv`, une ligne par action, avec une colonne plate par champ ; les horodatages sont en ISO 8601 (UTC) et toute valeur contenant une virgule est mise entre guillemets : ```csv timestamp,action,category,actorEmail,actorId,actorType,actorRole,resourceType,resourceId,resourceName,status,errorMessage 2026-01-14T03:14:07.000Z,member.role_changed,Member,admin@acme.example,usr_8f3a,user,owner,member,usr_2b91,jordan@acme.example,success, 2026-01-14T03:15:22.000Z,provider.updated,Provider,admin@acme.example,usr_8f3a,user,owner,provider,prov_openai,OpenAI,success, ``` L'export JSON (`audit-logs-<timestamp>.json`) porte les mêmes lignes en objets complets, plus les champs que le CSV aplatit — le diff `previousState`/`newState` et l'`integrityHash` par ligne. Choisis JSON quand un système en aval a besoin de la charge avant/après ou doit re-vérifier chaque ligne contre la chaîne SHA-256 (vois la section « Rétention et intégrité » plus bas) ; choisis CSV quand une personne l'ouvre dans un tableur. ## Rétention et intégrité Les lignes d'audit sont immuables : les modifications et suppressions sont elles-mêmes auditées, et le schéma de ligne porte un hash d'intégrité que tu peux vérifier contre l'export. Une tâche planifiée quotidienne re-vérifie la chaîne de hachage côté serveur et écrit une entrée d'audit `security` si la vérification échoue — ainsi une altération ou une suppression hors bande ressort même si personne ne lance la vérification manuelle. Une vérification en échec déclenche aussi une notification critique dans l'app pour les admins de l'organisation et part vers Slack quand un canal de notification Slack est configuré. La rétention est de 90 jours par défaut et se configure sur la page de politique de rétention (30 à 365 jours). Les lignes qui vieillissent sont retirées par la prochaine passe de nettoyage — il n'y a pas de fenêtre de soft-delete pour les données d'audit. ## Où cela s'inscrit Le journal d'audit est le côté lecture de toute autre fonction gouvernance : la conservation légale nomme les holds qu'elle a placés, les demandes des personnes concernées loggent chaque étape de cascade, la politique run-code logge les URLs que chaque sandbox a tenté d'atteindre. Quand une question commence par _qui, quand, quoi_, le journal d'audit est la réponse. La page compagnon est la [politique de rétention](/fr/platform/admin/governance/policies-and-limits) — elle contrôle combien de temps ces lignes restent avant que le nettoyage ne les retire. # Corbeille Source: https://tale.dev/docs/fr/platform/admin/governance/trash Corbeille est la surface de récupération pour les lignes que la rétention a soft-supprimées sans encore les avoir hard-supprimées. Quand un thread de chat, un document, un modèle de prompt ou une exécution de workflow dépasse sa fenêtre de rétention, il se déplace ici pour la fenêtre de grâce configurée avant que la prochaine passe de nettoyage ne le retire pour de bon. Les Administrateurs et Propriétaires lisent cette page quand un membre redemande un artefact supprimé, quand un workflow a supprimé le mauvais élément, ou quand un audit doit savoir si une ligne est encore récupérable. ## Une restauration mise en pratique Pour restaurer un thread d'historique de chat, ouvre **Paramètres > Gouvernance > Corbeille** et bascule le filtre **Catégorie** sur **Historique de chat**. Chaque ligne porte le type, le nom, le propriétaire, le statut et le moment de mise à la corbeille. Clique sur **Restaurer** sur la ligne, confirme dans la boîte de dialogue, et la ligne retourne dans sa liste source — les threads de chat réapparaissent dans la boîte de réception des conversations, les documents dans la base de connaissances, les prompts dans la bibliothèque de prompts. Restaurer une ligne expirée par la rétention demande de taper `restore` pour confirmer et est audité comme un dépassement de la politique de rétention. ## Les deux statuts **Mis à la corbeille** est l'état soft-delete normal. La fenêtre de rétention de la ligne a expiré, elle s'est déplacée à la corbeille, et la fenêtre de grâce tourne encore. Restaurer ramène la ligne dans sa liste source sans dépasser la politique. **Expiré** est le second état — la fenêtre de grâce s'est écoulée et la ligne est en file pour suppression définitive au prochain nettoyage. Restaurer reste possible mais est un dépassement : la boîte de dialogue te demande de taper `restore` et le journal d'audit enregistre le dépassement avec ton nom. ## Les catégories La corbeille contient des lignes de nombreuses catégories. Le filtre de catégorie change la vue par onglet : - Historique de chat (threads) - Documents - Fichiers temporaires - Modèles de prompt - Retours sur messages - Clients - Fournisseurs - Conversations externes - Métadonnées de message - Exécutions de workflow - Logs de déclencheur de workflow - Registre d'utilisation - Logs d'audit - Événements de filtre de chat - Audit de mémoire Chaque catégorie respecte sa propre fenêtre de rétention et sa propre fenêtre de grâce — réglées dans la politique de rétention dans [politiques et limites](/fr/platform/admin/governance/policies-and-limits). ## Interaction avec la conservation légale Les lignes sous conservation légale n'apparaissent pas dans la corbeille — le hold les épingle hors de portée de chaque étape de rétention. Quand tu tentes de supprimer une ligne sous hold depuis sa liste source, Tale refuse avec le message **La suppression est bloquée par un legal hold actif**. Lever le hold laisse la rétention faire passer la ligne par la fenêtre de corbeille comme les autres catégories. ## La fenêtre de grâce La fenêtre de grâce est configurable par catégorie dans la politique de rétention. Une grâce de zéro saute la corbeille entièrement — la passe de nettoyage hard-supprime la ligne immédiatement quand la rétention se déclenche. Une grâce au-dessus de zéro garde la ligne dans la corbeille ce nombre de jours et la fait apparaître ici pendant la fenêtre Administrateur où restaurer reste peu coûteux. ## Où cela s'inscrit Corbeille est la seconde chance que la rétention donne à chaque catégorie avant que la passe de nettoyage ne retire une ligne pour de bon. Elle s'associe à [politiques et limites](/fr/platform/admin/governance/policies-and-limits) — la page rétention règle les fenêtres ; cette page est la vue de récupération que ces fenêtres alimentent. La page compagnon est [conservation légale](/fr/platform/admin/governance/legal-hold), le seul mécanisme qui bat la rétention avant qu'une ligne n'atterrisse dans la corbeille. # Demandes des personnes concernées Source: https://tale.dev/docs/fr/platform/admin/governance/data-subject-requests Demandes des personnes concernées est le workflow que Tale livre pour honorer l’article 17 du RGPD (droit à l’effacement) et le droit équivalent CCPA sous la loi californienne. Chaque demande devient un reçu : il nomme la personne concernée, le code de motif, l’échéance SLA et la cascade de lignes que le système a effacées dans les threads, documents, exécutions de workflow et modèles de prompts personnels. Les Administrateurs et Propriétaires lisent cette page quand une personne dépose une demande, quand une échéance approche, ou quand un audit demande le reçu d’un effacement passé. <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.](/images/platform/governance-data-subject-requests.webp) </Frame> ## Un dépôt mis en pratique Pour déposer une demande, ouvre **Paramètres > Gouvernance > Demandes des personnes concernées** et clique sur **Déposer une demande**. Choisis la personne, choisis un code de motif (consentement retiré, plus nécessaire, traitement illégal, obligation légale, opposition, mineur ou fin de contrat) et ajoute une narration libre. La demande entre dans une fenêtre d’attente avant l’exécution de la cascade — tout Administrateur peut annuler pendant la fenêtre. Une fois la fenêtre écoulée, la cascade efface les threads, documents, exécutions de workflow, embeddings RAG et prompts personnels de la personne, et le reçu enregistre les compteurs par catégorie. ## Cycle de vie du statut | Nom | Par défaut | Description | | ------------------------ | --------------- | ------------------------------------------------------------------------------------------------------- | | En attente | état initial | La demande est déposée et attend la fenêtre d’attente ou la seconde approbation administrateur. | | En attente d’approbation | double contrôle | Un second Administrateur doit approuver avant que la cascade ne s’exécute. | | En cours | mid-cascade | La cascade est en cours ; les compteurs partiels se mettent à jour à mesure que chaque catégorie finit. | | Terminée | terminal | Chaque catégorie effacée sans erreur. | | Partielle | terminal | Certaines lignes ont été ignorées — généralement une conservation légale les a bloquées. | | Échouée | terminal | La cascade a rencontré une erreur ; le reçu nomme la catégorie en échec. | | Bloquée | terminal | Une conservation légale active bloque chaque étape de cascade. | | Annulée | terminal | Un Administrateur a annulé avant que la fenêtre d’attente n’expire. | ## Suivi du SLA Chaque demande porte une échéance niveau de service — par défaut, 30 jours depuis le dépôt. La liste des demandes affiche les jours restants ou un badge en retard par ligne. L’article 12(3) du RGPD autorise une prolongation unique pour les cas complexes ; l’action **Prolonger l'échéance** consigne la prolongation sur le reçu avec le nom de l’administrateur demandeur et une narration. ## Interaction avec la conservation légale Les données d’une personne ne sont _pas_ effacées tant qu’elles sont sous conservation légale. Les lignes sous hold apparaissent comme **Ignorées par hold** dans les compteurs par catégorie du reçu ; lever le hold et relancer la demande termine l’effacement. Le statut Bloquée se déclenche quand un hold couvre toutes les catégories dès le départ — la cascade ne s’exécute pas, et le reçu reflète le blocage. ## Les catégories de cascade Le reçu ventile les lignes effacées par catégorie — threads, documents, exécutions de workflow, modèles de prompts, documents RAG retirés du magasin vectoriel. Lis le drawer pour voir les compteurs et la timeline d’audit ; le journal d’audit dans la même zone Gouvernance porte la chaîne d’événements complète (`gdpr_erasure_requested`, `gdpr_erasure_executed`, `gdpr_erasure_extended`, `gdpr_erasure_cancelled`). ## Où cela s’inscrit Demandes des personnes concernées est le visage conformité de la rétention — le chemin audité, à double contrôle, qui efface une personne précise sur demande au lieu du balayage chronométré que la rétention applique à tous. La page compagnon est [conservation légale](/fr/platform/admin/governance/legal-hold) — elle couvre comment mettre la rétention et les cascades d’effacement en pause pour les litiges avant qu’elles ne s’exécutent. # Analyse des retours Source: https://tale.dev/docs/fr/platform/admin/governance/feedback-analytics Analyse des retours est le dashboard qui transforme les pouces par message et les notations par chat en courbes de tendance. Les membres laissent le retour inline dans le chat ; cette page l'agrège par agent, par modèle et dans le temps, pour que la régression du changement de voix de la semaine dernière soit visible comme un chiffre, pas comme un pressentiment. Les Administrateurs et Propriétaires lisent cette page quand un changement de modèle ressemble à une dégradation, quand un agent performe moins que les autres, ou quand la direction veut la posture qualité approximative de chaque agent dans l'organisation. ## Un drill-down mis en pratique Ouvre **Paramètres > Gouvernance > Retours** et la vue par défaut est le ratio org-wide sur les 30 derniers jours. Bascule la ventilation sur **Par agent** pour voir le ratio par agent — trie par volume de retours pour trouver les agents que les membres utilisent vraiment, puis clique dans l'un pour voir son historique de modèles à côté du même ratio dans le temps. La vue split-par-modèle est la même donnée découpée selon le modèle qui a produit chaque réponse notée. ## Les deux signaux **Retour pouces** est le signal par message — un pouce en haut ou un pouce en bas sur une réponse d'agent. Le pouce porte un commentaire libre optionnel ; le commentaire est par ligne et n'entre jamais dans le ratio. Les membres peuvent laisser les deux, modifier l'un ou retirer entièrement ; la timeline reflète le dernier état. **Notations de chat** est le signal par conversation — la notation d'une à cinq étoiles qui apparaît à la fin d'une conversation. Les notations portent aussi un commentaire optionnel. Les notations de chat sont plus grossières que les pouces et utiles pour suivre l'ambiance au niveau agent sur de nombreux tours, là où les pouces individuels seraient du bruit. ## Ventilations Le dashboard découpe selon trois dimensions : - **Agent** — chaque agent de l'organisation a sa propre ligne avec ratio, volume et tendance. - **Modèle** — chaque modèle qui a produit une réponse notée contribue ; utile quand tu compares un primaire à son repli. - **Temps** — la tendance est quotidienne pour les 30 derniers jours et hebdomadaire pour les fenêtres plus longues. ## Commentaires libres Les commentaires apparaissent sous les chiffres agrégés en liste. Trie par récence ou par sentiment ; clique pour rejoindre la conversation en contexte et voir ce à quoi la réponse notée répondait. Les commentaires sont soumis à la même politique de rétention que les conversations auxquelles ils appartiennent ; si un thread est purgé ou mis à la corbeille, ses commentaires partent avec. ## Où cela s'inscrit Analyse des retours est le pouls de chaque agent dans l'organisation — l'endroit où une régression de voix ou de comportement de modèle apparaît avant que quelqu'un la signale. La page compagnon est [analyse d'utilisation](/fr/platform/admin/governance/usage-analytics) — les mêmes agents et modèles, découpés par dépense et volume de tokens au lieu de qualité. # Agents (vue Admin) Source: https://tale.dev/docs/fr/platform/admin/agents La vue Admin des agents est l’annuaire à l’échelle de l’organisation de chaque agent qui existe dans Tale, peu importe qui l’a construit. Les Éditeurs et Développeurs ne voient que les agents auxquels ils ont accès dans leur propre périmètre ; les Administrateurs et Propriétaires les voient tous, plus les leviers de gouvernance par agent et la piste d’audit par agent. Cette page couvre la surface Admin — ce que la table montre, ce qu’un Admin peut changer, et ce qui reste sous le contrôle du propriétaire de l’agent. Cette page ne t’apprend pas à construire un agent. C’est la vue Éditeur sous [Agents](/fr/platform/agents/concepts). Ce qui suit est le côté supervision : comment trouver un agent, comment intervenir quand l’un d’eux a besoin d’attention, et comment les frontières de rôle tiennent quand tu le fais. <Frame caption="La liste des agents à l’échelle de l’organisation — un dossier déplié sur ses lignes d’agents, chacune avec son modèle et sa catégorie. Un Admin voit ici chaque agent de l’org."> ![La liste des agents avec un dossier déplié montrant des lignes d’agents, chacune nommant un agent aux côtés de son modèle principal et de sa catégorie.](/images/platform/agents-list-expanded.webp) </Frame> ## Ce que la table montre Ouvre **Paramètres > Agents** pour atterrir sur la liste à l’échelle de l’org. Chaque ligne nomme un agent et montre son modèle primaire, sa catégorie, l’équipe à laquelle il appartient (s’il y en a une), et la date de la dernière édition. La liste est cherchable par nom et filtrable par catégorie, équipe et statut (actif ou désactivé). Le tri par défaut est « le plus récemment édité d’abord » — utile quand tu veux voir ce qui a changé depuis la dernière fois. Cliquer une ligne ouvre le même éditeur d’agent qu’un Éditeur ou Développeur verrait, mais avec la lentille Admin : chaque onglet est visible, chaque liaison est éditable, et l’onglet de journal d’audit montre l’historique complet d’édition avec l’acteur et le diff par enregistrement. ## Ce qu’un Admin peut faire qu’un Éditeur ne peut pas Les Administrateurs héritent de chaque permission qu’Éditeur et Développeur portent sur la surface agent. Au-dessus, la vue Admin ajoute trois mouvements de gouvernance : - **Désactiver un agent.** Un agent désactivé n’apparaît plus dans les pickers et ne répond plus aux nouvelles requêtes, mais ses conversations, exécutions et piste d’audit sont préservées. Réactiver restaure le comportement précédent. Va vers désactiver quand un agent se comporte mal et que tu dois l’arrêter sans perdre le contexte. - **Réassigner la propriété.** Le propriétaire d’un agent est l’équipe ou le membre qui en est responsable. Réassigner transfère l’agent à une autre équipe ou un autre membre ; le propriétaire précédent perd l’accès en écriture sauf s’il partage la nouvelle équipe. Va vers réassigner quand une équipe est réorganisée ou qu’un propriétaire part. - **Appliquer une politique de gouvernance.** Les Administrateurs peuvent attacher une politique de gouvernance à un agent — approbations requises sur les écritures, familles de tools autorisées, intégrations autorisées. La politique écrase la configuration propre de l’agent en cas de conflit ; le propriétaire voit la politique comme un badge en lecture seule dans l’éditeur. ## Ce qui reste avec le propriétaire de l’agent La plupart de l’édition quotidienne reste avec la personne qui a construit l’agent. Renommer, modifier les instructions, ajuster les liaisons de connaissance, basculer les tools, changer de modèle, publier de nouvelles versions — tout ça arrive dans l’éditeur d’agent sous les permissions du propriétaire. La vue Admin sert à intervenir, pas à prendre le contrôle. Si tu te retrouves à éditer les agents des autres en routine, la bonne réponse est généralement une politique de gouvernance qui scope le comportement, pas une édition manuelle. ## Audit et historique Chaque enregistrement sur un agent atterrit dans le journal d’audit avec l’acteur, l’horodatage et le champ qui a changé. La vue Admin expose la tranche par agent de ce journal sous l’onglet **Historique** dans l’éditeur d’agent. Les mêmes données sont également joignables depuis le journal d’audit à l’échelle de l’org sous **Paramètres > Gouvernance**. ## Où cela s’inscrit La vue Admin des agents est le pendant supervision à la vue construction de l’Éditeur — mêmes agents, lentille différente. Va la chercher la plupart du temps seulement quand quelque chose a besoin d’attention ; le travail quotidien arrive dans l’éditeur d’agent sous [Concepts agents](/fr/platform/agents/concepts). Quand la bonne réponse est de scoper le comportement pour une classe d’agents plutôt qu’un seul, la lecture suivante est la surface des politiques de gouvernance — voir [Membres et rôles](/fr/platform/admin/members-and-roles) pour comment les politiques s’attachent aux rôles. # Membres et rôles Source: https://tale.dev/docs/fr/platform/admin/members-and-roles Les membres sont les personnes de ton organisation qui peuvent se connecter à Tale. Les rôles contrôlent ce que chaque membre peut faire — lire, écrire, configurer, gouverner. Cette page est la référence canonique pour les six rôles et les permissions par ressource que chaque rôle porte. Six rôles couvrent presque chaque équipe à laquelle Tale est livré. Les Administrateurs et Propriétaires lisent cette page quand ils montent une équipe pour la première fois, quand un audit demande qui a quel accès, ou quand ils doivent décider entre Éditeur et Développeur pour un nouveau venu. <Frame caption="La section Membres sous Paramètres > Organisation — chaque compte et le rôle qui le borne."> ![La page de paramètres Organisation avec sa section Membres listant le propriétaire de l’espace de travail et un bouton Ajouter un membre.](/images/get-started/settings-organization-members.webp) </Frame> ## Ajouter un membre Pour ajouter une personne à ton organisation, ouvre **Paramètres > Organisation**, fais défiler jusqu’à la section **Membres** et clique sur **Ajouter un membre**. Renseigne son **Nom**, son **E-mail** et son **Rôle**, puis définis un **Mot de passe** — Tale n’envoie pas d’invitation par e-mail, un mot de passe est donc requis pour créer un nouveau compte. (Si l’e-mail correspond déjà à un compte Tale, aucun mot de passe n’est demandé : la personne se connecte avec ses identifiants existants et est simplement ajoutée à cette organisation.) Lors de l’**Ajouter un membre**, Tale affiche les nouveaux identifiants **une seule fois**, en rappelant de les enregistrer maintenant : ils ne seront plus affichés. Transmets-les au nouveau membre par un autre canal ; il n’y a pas d’e-mail de réinitialisation. Quiconque oublie ensuite son mot de passe contacte un administrateur, qui peut en définir un nouveau depuis la même section Membres. Choisis le rôle dans le formulaire avant de valider ; le promouvoir ou le changer ensuite est une modification en un clic dans la même section Membres. ## Les six rôles **Propriétaire** a chaque permission qu’a Admin, plus celle qui manque à Admin : transférer la propriété et supprimer l’organisation. La plupart des équipes ont exactement un Propriétaire ; certaines en gardent deux pour la continuité. **Admin** gouverne l’organisation : membres, fournisseurs, branding, politiques de gouvernance, intégrations, le journal d’audit. Les Administrateurs font tout ce que fait Éditeur et tout ce que fait Développeur, plus la surface de configuration. Ils ne peuvent pas transférer la propriété. **Développeur** construit : agents, automatisations, intégrations, clés API, serveurs MCP. Les Développeurs peuvent lire chaque ressource et écrire dans la plupart, y compris les politiques de gouvernance (lecture seule). Va vers Développeur quand quelqu’un a besoin du plan API et de l’outillage d’intégration. **Éditeur** organise et opère : agents, base de connaissances (documents, clients, produits, fournisseurs, sites web), boîte de réception des conversations, approbations, bibliothèque de prompts. Les Éditeurs peuvent lire les workflows mais pas les modifier ; ils peuvent lire les intégrations mais pas les configurer. Va vers Éditeur quand quelqu’un fait le travail produit quotidien sans toucher au plan API ou intégrations. **Membre** exécute : chat, parcourt la base de connaissances, lit les conversations et approbations qui lui sont assignées. Les Membres n’écrivent que dans le feedback de message (pouce en haut / en bas). Va vers Membre comme défaut — la plupart des utilisateurs dans la plupart des organisations sont Membres. **Désactivé** n’a aucune permission. Utilise ça pour révoquer l’accès sans supprimer le compte ; les transcriptions et l’historique d’audit restent intacts, et réactiver restaure le rôle précédent. ## La matrice de permissions | Ressource | Propriétaire | Admin | Développeur | Éditeur | Membre | Désactivé | | ------------------------- | ------------ | ----- | ----------- | ------- | ------ | --------- | | Agents | R / W | R / W | R / W | R / W | R | — | | Documents | R / W | R / W | R / W | R / W | R | — | | Produits | R / W | R / W | R / W | R / W | R | — | | Clients | R / W | R / W | R / W | R / W | R | — | | Fournisseurs | R / W | R / W | R / W | R / W | R | — | | Projets | R / W | R / W | R / W | R / W | R | — | | Sites web | R / W | R / W | R / W | R / W | R | — | | Conversations | R / W | R / W | R / W | R / W | R | — | | Messages de conversation | R / W | R / W | R / W | R / W | R | — | | Approbations | R / W | R / W | R / W | R / W | R | — | | Exécutions workflow | R / W | R / W | R / W | R | R | — | | Traitement workflow | R / W | R / W | R / W | R | R | — | | Intégrations | R / W | R / W | R / W | R | R | — | | Configs OneDrive sync | R / W | R / W | R / W | R | R | — | | Templates de prompts | R / W | R / W | R / W | R / W | R | — | | Journaux d’audit | R / W | R / W | R / W | R / W | R | — | | Politiques de gouvernance | R / W | R / W | R | R | R | — | | Feedback de messages | R / W | R / W | R / W | R / W | R / W | — | | Serveurs MCP | R / W | R / W | R / W | R | R | — | R = lecture, W = écriture, — = aucun accès. La matrice est la description faisant autorité de ce que chaque rôle peut faire sur les ressources que Tale piste ; les lignes sont l’ensemble qu’utilise le système de permissions interne au produit à la requête. ## La surface Paramètres et le menu Les Membres, Éditeurs et utilisateurs Désactivés ne voient pas la surface de configuration — seulement leurs propres paramètres personnels. Les Développeurs voient les paramètres d’organisation mais pas le sous-arbre gouvernance (sauf vues en lecture). Les Administrateurs et Propriétaires voient tout. Le menu des paramètres est groupé en **Personnel** (Compte, Préférences, Environnement — chaque rôle), **Organisation** (la section Membres, Équipes, Fournisseurs IA, Branding, Gouvernance et le reste — Admin et Propriétaire, les Développeurs en voyant un sous-ensemble) et **Développement** (la surface API et résidence des données). La gouvernance est un élément dans le groupe Organisation, pas un groupe à part, et demande l’accès Admin. ## Cas limites **Transférer la propriété** demande qu’un Propriétaire existant nomme un Admin ou Propriétaire actuel ; le nouveau rôle Propriétaire prend effet immédiatement. Le Propriétaire précédent devient Admin sauf rétrogradation explicite. **Avertissement « dernier Admin ».** La section Membres avertit quand on retire ou rétrograde le dernier Admin ou Propriétaire. L’action est autorisée — Tale ne te verrouille pas dehors — mais tu devrais garder au moins deux comptes Admin-ou-Propriétaire pour la continuité. **Réinitialiser la 2FA** se trouve sur la ligne du membre dans la section Membres. Réinitialiser efface le second facteur ; le sign-in suivant réenrôle. ## Où cela s’inscrit Les rôles sont la surface d’accès que touche chaque autre page admin : le SSO les authentifie, les clés API leur appartiennent, les journaux d’audit les nomment, les politiques de gouvernance scopent le comportement par rôle. La lecture suivante dépend de ce que tu fais ensuite. Si tu câbles le sign-in à ton fournisseur d’identité, [authentification](/fr/self-hosted/configuration/authentication) couvre les quatre modes. Si tu scopes l’accès par équipe plutôt que par rôle seul, [Équipes](/fr/platform/admin/teams) couvre la couche par équipe. # Équipes Source: https://tale.dev/docs/fr/platform/admin/teams Une équipe est un groupe nommé de membres qui partage l’accès aux agents, prompts, projets, intégrations et conversations. Là où les rôles définissent ce qu’une personne _peut_ faire, les équipes définissent dans quelle tranche des données de l’org cette personne travaille. La plupart des orgs finissent avec une poignée d’équipes — support, ventes, opérations — et la plupart des décisions quotidiennes de permission atterrissent sur la frontière équipe, pas sur la frontière rôle. Les Administrateurs gèrent les équipes sous **Paramètres > Équipes**. Cette page est la référence pour ce qu’une équipe possède, comment marche l’appartenance, et comment la frontière équipe interagit avec les permissions basées sur les rôles documentées sous [Membres et rôles](/fr/platform/admin/members-and-roles). Lis-la une fois quand tu mets les équipes de l’org en place ; reviens quand tu réorganises. <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 — Growth, Platform engineering et Customer success — chacune avec un membre et la date de son ajout, à côté d’un bouton Créer une équipe.](/images/platform/settings-teams.webp) </Frame> ## Ce qu’une équipe possède Une équipe porte l’appartenance et un ensemble de ressources qui lui sont cadrées. Les ressources sont : - **Agents** — les agents créés avec un cadre d’équipe ne sont visibles et éditables que par les membres de cette équipe. Les agents à l’échelle de l’org restent visibles pour quiconque a le bon rôle. - **Prompts** — les prompts enregistrés avec visibilité `Équipe` n’apparaissent que pour les membres de cette équipe. Les prompts personnels restent privés à leur propriétaire ; les prompts Globaux sont visibles à l’échelle de l’org. - **Projets** — les projets peuvent être assignés à une équipe ; les membres de l’équipe héritent de l’accès au projet sans être ajoutés un par un. - **Intégrations** — les intégrations restreintes à certaines équipes (sous le levier **Équipes autorisées** dans **Paramètres > Intégrations**) n’apparaissent que dans les pickers de ces équipes. - **Conversations** — les conversations de canal client peuvent être routées vers une équipe ; le filtre de l’inbox respecte le cadre équipe. Une ressource sans cadre équipe reste visible pour quiconque dont le rôle l’autorise. Les équipes sont une couche de cadrage _additive_ — elles rétrécissent la visibilité, jamais ne l’élargissent. ## Créer une équipe Ouvre **Paramètres > Équipes** et clique sur **Créer une équipe**. Donne à l’équipe un nom (`Support`, `Ventes`, `Opérations`) et une description optionnelle ; le nom apparaît partout où l’équipe surgit — pickers, badges, onglets de la bibliothèque de prompts, champ équipes-autorisées de l’intégration. Enregistrer crée une équipe vide que tu peux remplir de membres depuis la ligne de l’équipe. La ligne de l’équipe porte trois sous-vues : **Membres** (qui est dans l’équipe), **Ressources** (ce que l’équipe possède) et **Paramètres** (nom, description et cycle de vie de l’équipe). La vue Ressources est la façon la plus simple de voir jusqu’où une équipe peut atteindre ; elle sert aussi de surface d’audit quand quelqu’un demande pourquoi une équipe voit un agent particulier. ## Ajouter et retirer des membres Ouvre la ligne de l’équipe et clique sur **Ajouter des membres**. Le picker liste les membres de l’org ; en cocher un l’ajoute à l’équipe. Un membre peut appartenir à plusieurs équipes ; son accès est l’union de chaque équipe dans laquelle il est plus la portée à l’échelle de l’org de son rôle. Retirer un membre d’une équipe arrache la visibilité cadrée équipe à la requête suivante ; les chats en vol se terminent, mais le thread suivant ne voit pas les ressources de l’équipe. ## Équipe versus rôle Le rôle décide ce qu’une personne peut faire ; l’équipe décide à quoi elle peut le faire. Un utilisateur de rôle Membre dans l’équipe Support peut lire les agents de l’équipe support mais ne peut pas les éditer ; un utilisateur de rôle Développeur dans l’équipe Support peut lire et écrire les agents de l’équipe support mais ne peut pas voir ceux des Ventes. Les équipes n’accordent jamais des capacités que le rôle n’a pas ; les rôles n’élargissent jamais la visibilité au-delà du cadre équipe. Quand tu as besoin d’une décision de permission que les rôles et équipes existants ne peuvent pas exprimer, le levier suivant est une politique de gouvernance — voir [Membres et rôles](/fr/platform/admin/members-and-roles) pour comment les politiques s’attachent aux rôles, et la section gouvernance pour les champs de politique eux-mêmes. ## Supprimer une équipe Clique la ligne de l’équipe, puis **Supprimer l'équipe**. La suppression est définitive — l’équipe est partie, chaque ressource cadrée équipe qu’elle possédait passe à la visibilité à l’échelle de l’org, et les membres perdent la tranche cadrée équipe de leur accès. Pas d’annulation ; les ressources orphelines restent joignables par quiconque dont le rôle l’autorise, ce qui est rarement le bon résultat. Va vers supprimer quand une équipe est vraiment retirée, pas quand elle se réorganise. ## Où cela s’inscrit Les équipes sont la couche de cadrage juste sous les rôles — les rôles disent _quoi_, les équipes disent _où_. La lecture suivante naturelle dépend de la ressource que tu cadres : [Bibliothèque de prompts](/fr/platform/workspace/prompt-library) pour comment les prompts s’attachent aux équipes, [Intégrations (vue Admin)](/fr/platform/admin/integrations) pour le levier équipes-autorisées, et [Projets](/fr/platform/projects/overview) pour l’assignation projet-à-équipe. # Intégrations (vue Admin) Source: https://tale.dev/docs/fr/platform/admin/integrations Paramètres > Intégrations est la surface des identifiants pour chaque système tiers avec lequel Tale parle au nom de l’organisation. Les Administrateurs installent les intégrations une fois ; les agents, workflows et la pipeline documents les utilisent partout ailleurs. Cette page couvre le côté admin — ce que montre la liste, comment marchent installation et rotation, ce qu’un Admin peut scoper, et en quoi la surface diffère des serveurs MCP. L’histoire fonctionnelle de chaque intégration (ce qu’elle fait, quels périmètres elle demande, ce qu’un agent peut appeler) vit un onglet plus loin sur les pages par intégration et dans la page de concept inter-intégrations. Ce qui suit est la surface opérations : installer, roter, restreindre, révoquer. <Frame caption="Le catalogue des intégrations sous Ajouter une intégration — chaque connecteur que Tale embarque, filtrable par catégorie."> ![Le catalogue des intégrations montrant une grille de cartes de connecteurs — Slack, Gmail, Google Drive, GitHub, Tavily et plus — chacune avec une action Connecter.](/images/platform/integrations-catalog.webp) </Frame> ## Ce que la liste montre Ouvre **Paramètres > Intégrations** pour atterrir sur les intégrations installées de l’org. Chaque ligne nomme une intégration, montre sa catégorie (communication, stockage, identité, connaissance, contrôle de source, commerce, IA), le type d’identifiant (OAuth2, clé API, jeton d’app) et le statut de connexion (connectée, en attente, erreur). La liste est filtrable par catégorie et par statut. Le catalogue des intégrations disponibles est à un clic sous **Ajouter une intégration**. Le catalogue ship actuellement Slack, Microsoft Teams, Discord, Gmail, Outlook, Twilio, Microsoft 365, Google Drive, Confluence, WebDAV, Tavily, GitHub, Shopify et AI image ; le même catalogue est la source que documente la vue d’ensemble des intégrations. ## Installer une intégration Choisis une intégration du catalogue et clique sur **Connecter**. L’intégration déclare le type d’identifiant qu’elle attend et les périmètres dont elle a besoin ; Tale exécute la danse OAuth pour les intégrations OAuth et montre un formulaire pour les intégrations à clé API. Une fois l’identifiant déposé, Tale le vérifie avec un appel à vide vers le système amont avant d’enregistrer — un échec apparaît comme erreur de connexion avec le message amont attaché. Certaines intégrations portent des sous-options à l’installation. Microsoft 365 te laisse choisir s’il faut activer la sync OneDrive, la sync SharePoint, les deux, ou seulement le SSO ; GitHub te laisse choisir les dépôts auxquels l’org accorde l’accès ; Slack demande dans quels canaux le bot peut poster. Les sous-options peuvent être modifiées plus tard depuis la ligne de l’intégration sans réinstaller. ## Mettre à jour les définitions depuis le catalogue livré La définition de chaque intégration — son schéma de configuration, son connecteur, son icône — est copiée dans l’organisation à sa création et reste intacte ensuite ; une mise à jour de la plateforme ne la change donc jamais dans ton dos. **Mettre à jour les intégrations livrées** dans le menu **Ajouter une intégration** remplace chaque définition livrée qui diffère du catalogue courant par la dernière version. Les identifiants, les secrets et les intégrations que tu as ajoutées toi-même restent intacts ; la version précédente de chaque définition remplacée est conservée sur le serveur, pour qu’un opérateur puisse la récupérer. ## Roter les identifiants Pour roter, ouvre la ligne de l’intégration et clique sur **Roter les identifiants**. Les intégrations OAuth refont la danse avec les mêmes périmètres ; les intégrations à clé API montrent un champ pour la nouvelle clé. L’ancien identifiant arrête de marcher dès que le nouveau est vérifié — il n’y a pas de fenêtre de chevauchement pour les identifiants au niveau de l’intégration. Va vers la rotation au rythme que ta politique de sécurité impose, ou chaque fois que le système amont rapporte un identifiant compromis. ## Restreindre une intégration Au-delà des identifiants, une intégration porte deux leviers de cadrage sous sa ligne : - **Rôles autorisés.** Restreins quels rôles peuvent appeler l’intégration depuis leurs agents et workflows. Le défaut est chaque rôle écrivain (Éditeur, Développeur, Administrateur, Propriétaire) ; le rétrécir est la façon de garder, disons, l’intégration Twilio hors des agents construits par des Membres. - **Équipes autorisées.** Restreins quelles équipes peuvent appeler l’intégration depuis leurs agents et workflows. Utile quand l’identifiant appartient au travail d’une équipe (le Slack de l’équipe support) et que tu ne veux pas qu’il fuie vers une autre. Les deux leviers sont appliqués à la requête, pas à l’installation — changer un levier prend effet au prochain appel. ## Révoquer une intégration Clique la ligne, puis **Déconnecter**. Une intégration déconnectée arrête d’authentifier immédiatement ; les agents et workflows qui en dépendent font remonter une erreur de configuration au prochain appel. La ligne reste dans la liste avec un badge déconnecté pour que la piste d’audit survive. Reconnecter parcourt le flux d’identifiants de zéro. ## Bot Slack et notifications Slack est bidirectionnel. Au-delà de l’agent qui appelle Slack (poster des messages, lire des canaux), l’org peut laisser des personnes parler à un agent depuis Slack et pousser des événements système dans un canal. Les deux se configurent sur la ligne Slack connectée, et les deux utilisent le même identifiant OAuth — pas de seconde connexion. Chaque org apporte sa propre app Slack, configurée entièrement depuis la ligne Slack — il n’y a rien à définir sur le déploiement. Quand tu connectes Slack, la ligne affiche un panneau **Configurer votre application Slack** avec un manifeste d’app prêt à coller et les deux URLs auxquelles il fait référence : l’URL de requête des Event Subscriptions (`/api/integrations/slack/events`) et l’URL de redirection OAuth. Le manifeste pré-remplit les portées du bot, les événements `app_mention` et `message.im` ainsi que les deux URLs, si bien que créer l’app sur api.slack.com/apps ne prend que quelques clics. Recolle l'**ID client**, le **Secret client** et le **Secret de signature** de l’app dans la ligne, puis autorise via OAuth. Le secret de signature est ce qui vérifie les événements entrants, donc le bot reste muet tant qu’il n’est pas défini ; les messages entrants sont routés vers la bonne org via l’espace de travail Slack. Sur la ligne Slack connectée, un admin choisit **quel agent répond sur Slack** (une mention dans un canal ou un message direct démarre une réponse en thread de cet agent) et **quels canaux reçoivent les notifications**, avec une bascule par événement. Les événements livrés sont workflow échoué, workflow terminé et alertes de sécurité ; un thread Slack correspond à une conversation d’agent, et l’auteur Slack y est conservé plutôt qu’enregistré comme le système. ## Intégrations versus serveurs MCP Deux surfaces laissent un agent atteindre au-delà de Tale. Les **Intégrations** sont les connecteurs spécifiques au fournisseur, premier-party, documentés ici. Les **serveurs MCP** sont des processus externes qui exposent le Model Context Protocol ; l’org les enregistre sous **Paramètres > Serveurs MCP** et approuve chaque tool à son premier appel. Va vers une intégration quand une existe pour le système cible ; va vers les [serveurs MCP](/fr/platform/integrations/mcp-servers) quand aucune intégration ne couvre ton besoin. ## Où cela s’inscrit Les intégrations sont la moitié identifiants de l’histoire agent-vers-monde-extérieur ; la moitié agent (quels tools un agent obtient, comment il les appelle, à quoi ressemble la frontière de confiance) vit sous [Tools agents](/fr/platform/agents/tools). La lecture naturelle suivante pour un nouvel admin est [Vue d’ensemble des intégrations](/fr/platform/integrations/overview) — elle nomme chaque intégration livrée groupée par ce qu’elle fait et donne le setup par intégration d’un coup d'œil. # Clés API Source: https://tale.dev/docs/fr/platform/admin/api-keys Les clés API sont les identifiants à l’échelle de l’org que Tale émet pour qu’un code externe appelle son API REST sans humain dans la boucle. Une clé authentifie l’appelant comme étant l’organisation, scopée par le rôle que tu choisis quand tu la fabriques. Les Administrateurs et Développeurs gèrent les clés ; les autres rôles ne voient pas la page. Voilà la référence pour ce qu’est une clé, comment en créer une, comment la scoper, et comment la retirer sans casser ce qui en dépend. Les clés listées ici sont différentes des jetons de session par utilisateur que Tale émet à la connexion. Ceux-ci sont de courte durée et liés à une personne ; les clés API sont de longue durée et liées à l’organisation. Va vers une clé API quand tu branches un script, une tâche cron, un service interne, ou une intégration tierce à Tale ; va vers l’UI en-produit quand une personne est au clavier. <Frame caption="Paramètres > Clés API — là où les clés sont créées, rotées et révoquées."> ![La page de paramètres des clés API REST listant deux clés dont chacune n’affiche que son préfixe, sa date d’ajout et la mention Jamais utilisée, à côté d’un bouton Créer une clé API.](/images/get-started/settings-api-keys.webp) </Frame> ## Créer une clé Ouvre **Paramètres > Clés API** et clique sur **Créer une clé API**. Donne à la clé un nom qui dit qui ou quoi va l’utiliser (`Sync facturation`, `Relais Slack`, `ops-cron`), choisis le rôle qu’elle doit porter, et choisis l’expiration. Tale montre le secret exactement une fois à la création — copie-le dans ton gestionnaire de mots de passe ou ton système de déploiement avant de fermer la boîte de dialogue. Après, seul le préfixe de la clé est visible depuis la table. Le rôle que tu choisis scope tout ce que la clé peut faire. Une clé portant le rôle Développeur peut lire chaque ressource et écrire dans la plupart ; une clé portant le rôle Membre peut lire la base de connaissances et démarrer des chats mais rien configurer. Prends le plus petit rôle qui fait le job — les clés sont aussi dangereuses que le rôle qu’elles portent. ## Ce que la table montre La table des clés API liste chaque clé par nom, préfixe, rôle, créateur, horodatage de dernière utilisation et expiration. Le préfixe est les huit premiers caractères du secret — assez pour identifier la clé dans les journaux sans l’exposer. L’horodatage de dernière utilisation s’actualise à chaque requête réussie que fait la clé ; une clé non utilisée depuis des semaines est généralement sûre à retirer. La ligne de filtre te laisse rétrécir par rôle, créateur et fenêtre d’expiration. Le tri par défaut est « créées le plus récemment d’abord » ; le tri secondaire est « utilisées le plus récemment ». ## Roter une clé Pour roter, crée d’abord la nouvelle clé, déploie-la sur le système qui utilise l’ancienne, vérifie que la nouvelle fonctionne (l’horodatage de dernière utilisation s’actualise), et alors seulement révoque l’ancienne. Tale n’autorote pas les clés ; la discipline du chevauchement est la tienne. La rotation est le bon mouvement quand on soupçonne une fuite, quand quelqu’un ayant accès à la clé quitte l’organisation, ou au rythme que ta politique de sécurité impose. ## Révoquer une clé Clique la ligne, puis **Révoquer**. Une clé révoquée arrête d’authentifier immédiatement — toute requête en vol se termine, mais la suivante échoue avec `401`. Les clés révoquées restent dans la table pour la piste d’audit ; la ligne les marque comme révoquées et montre qui les a révoquées et quand. Pas d’annulation pour la révocation ; si tu révoques la mauvaise clé, fabriques-en une nouvelle. ## Périmètres et limites Chaque clé porte les permissions de son rôle au moment de chaque requête, pas au moment de la création. Si tu modifies les permissions d’un rôle via une politique de gouvernance, chaque clé portant ce rôle hérite du changement à la requête suivante. Les limites de débit de l’org s’appliquent par clé, pas par organisation ; une clé bruyante ne ralentit pas une clé tranquille. Une clé peut être restreinte plus encore par une allowlist IP à la création. L’allowlist prend une liste de blocs CIDR séparés par virgules ; les requêtes hors liste échouent avec `403`. Va vers l’allowlist IP quand le système appelant a une sortie stable et que tu veux de la défense en profondeur. ## Où cela s’inscrit Les clés API sont le pont entre Tale et le code externe ; elles s’asseyent à côté des [Intégrations](/fr/platform/admin/integrations) (systèmes tiers que Tale appelle) et des [Webhooks](/fr/platform/agents/webhook-triggers) (systèmes qui appellent Tale sur événement). La lecture suivante naturelle est l’API REST elle-même — voir la référence API dans l’onglet Develop pour la surface contre laquelle une clé authentifie, et voir [Membres et rôles](/fr/platform/admin/members-and-roles) pour la carte rôle-vers-permission que chaque clé hérite. # Fournisseurs IA Source: https://tale.dev/docs/fr/platform/admin/providers Paramètres > Fournisseurs IA est la surface où Tale rencontre les modèles qu’il sert. Une organisation toute neuve embarque un fournisseur connecté — **OpenRouter**, dont l’unique clé atteint les modèles de chat, vision, embedding, transcription, voix et image — et les Administrateurs ajoutent, éditent ou retirent des fournisseurs depuis ici. Chaque réponse que Tale diffuse est routée via un modèle résolu sur cette page ; y toucher change ce que le reste du produit peut faire. <Frame caption="Paramètres > Fournisseurs IA — les fournisseurs connectés, chacun avec son URL de base et la taille de sa liste de modèles."> ![La page de paramètres Fournisseurs IA listant un seul fournisseur connecté, OpenRouter, avec son URL de base et ses 52 modèles, à côté d’un bouton Ajouter un fournisseur et des contrôles de synchronisation du catalogue de modèles.](/images/get-started/settings-providers.webp) </Frame> ## Ce que montre la liste Ouvre **Paramètres > Fournisseurs IA** et tu atterris sur les fournisseurs que l’organisation a connectés. Chaque ligne nomme le fournisseur et montre si sa clé API est configurée. Cliquer une ligne ouvre le tiroir du fournisseur : son URL de base et sa clé, ses **Modèles par défaut**, et la liste **Modèles** elle-même — cherchable, avec les étiquettes de capacité qui décident où chaque modèle est utilisable. Le tiroir est là où se passe tout le travail par fournisseur. La vue liste est volontairement mince ; la profondeur est à un clic dedans. ## Ajouter un fournisseur Clique **Ajouter un fournisseur**. **Partir d'un fournisseur connu** choisit OpenAI, Anthropic ou OpenRouter et remplit le nom du fournisseur et l’URL de base — il ne reste plus qu’à ajouter ta clé API. Modifier le nom ou l’URL de base à la main fait revenir le sélecteur sur **Personnalisé**, la voie manuelle : un fournisseur est une **URL de base** plus une **clé API** — l’endpoint propre à un fournisseur direct, OpenRouter (`https://openrouter.ai/api/v1`) pour le catalogue le plus large, ou un serveur Ollama ou vLLM local sur ton réseau. La clé est stockée chiffrée et utilisée seulement pour appeler ce fournisseur. Une fois l’identifiant posé, remplis la liste de modèles : **Récupérer les modèles** tire la liste que l’API du fournisseur rapporte, **Ajouter un modèle** en déclare un à la main, et — une fois le catalogue de modèles de l’organisation synchronisé — choisir un modèle dans le catalogue depuis cette boîte de dialogue remplit son ID et ses capacités connues (fenêtre de contexte, tarification, raisonnement) au lieu de les saisir. Aucun modèle n’est appelable tant qu’il n’est pas dans la liste du fournisseur avec la bonne étiquette de capacité. Pour OpenAI, Anthropic et OpenRouter, l’URL de base reste verrouillée sur l’endpoint publié même après la création du fournisseur — ouvre le tiroir de la ligne, clique sur **Modifier les détails** sous **Général**, et le champ apparaît en lecture seule avec un bouton **Remplacer l'URL de base** à côté. Ne recours au remplacement que pour pointer le slug de ce fournisseur vers un proxy compatible ou un autre endpoint du même fournisseur ; l’URL de base de tout autre fournisseur reste modifiable directement, sans remplacement. ## La liste de modèles et les étiquettes de capacité Chaque modèle porte une ou plusieurs étiquettes de capacité — **Chat**, **Vision**, **Embedding**, **Transcription**, **Synthèse vocale**, **Génération d'images**, **Édition d'images**. Les étiquettes sont porteuses : elles décident dans quels sélecteurs un modèle apparaît et quelle capacité de la plateforme peut l’appeler. Un modèle sans étiquette correspondante n’apparaît jamais là où cette capacité est requise. **Masqué des sélecteurs de modèles** retire un modèle du composeur de chat et de la sélection de modèle des agents tout en le laissant pleinement utilisable par les agents et workflows qui le référencent déjà. C’est ainsi qu’une version supplantée ou dépréciée prend sa retraite sans casser les agents qui y sont liés. ## Modèles par défaut La carte **Modèles par défaut** nomme quel modèle chaque capacité utilise quand rien de plus spécifique n’est lié — le défaut de chat pour les nouveaux chats et nouveaux agents, plus les défauts de vision, embedding, génération d’images et transcription qu’utilisent les services d’arrière-plan. Changer un défaut n’affecte que les nouveaux objets ; les chats et agents existants gardent le modèle auquel ils étaient liés. Va vers les défauts quand tu déploies une nouvelle génération de modèle dans toute l’organisation sans rééditer chaque agent. ## Garder le catalogue à jour Deux contrôles gardent le catalogue à jour sans édition manuelle. La carte **Catalogue de modèles** rafraîchit les capacités de chaque modèle — tarification, fenêtre de contexte, raisonnement, vision — depuis le catalogue public d’OpenRouter chaque jour. La bascule **Auto-sync hebdomadaire de la config fournisseur** fusionne les nouvelles versions phares une fois par semaine dans la config fournisseur de l’organisation, masque les versions supplantées et laisse intact tout champ que tu as personnalisé. ## Où cela s’inscrit Les fournisseurs sont le bas de la pile — chaque agent, chaque chat, chaque étape de workflow qui produit du texte se résout via eux. Le catalogue de ce que chaque fournisseur livre et des étiquettes qu’il porte vit dans [Modèles](/fr/platform/models) ; la forme basée fichier de la même configuration vit sous [Configuration → providers](/fr/self-hosted/configuration/providers) ; et [Concepts d’agent](/fr/platform/agents/concepts) couvre comment le bouton modèle s’inscrit dans le modèle à quatre boutons dont un agent est bâti. # Authentification à deux facteurs Source: https://tale.dev/docs/fr/platform/admin/two-factor-authentication L’authentification à deux facteurs ajoute une seconde preuve d’identité par-dessus le mot de passe — un code à six chiffres d’une appli authenticator, ou un passkey WebAuthn. Tale embarque TOTP (mots de passe à usage unique basés sur le temps) compatible avec Google Authenticator, 1Password, Authy et toute autre appli qui suit le standard, plus les passkeys comme alternative résistante au phishing. La page couvre l’inscription par utilisateur, les passkeys, les codes de secours qui récupèrent un compte quand le téléphone n’est plus là, la politique d’application org-large et la réinitialisation admin pour un membre verrouillé. La 2FA est optionnelle par défaut. Les Administrateurs peuvent l’exiger pour toute l’organisation avec une fenêtre de grâce pour que les membres aient le temps de s’inscrire. ## Inscription par utilisateur Pour activer la 2FA sur ton propre compte, ouvre **Compte > Sécurité**. Clique sur **Activer la deux-facteurs**, confirme ton mot de passe et scanne le code QR avec une appli authenticator. Saisis le code à six chiffres que l’appli affiche pour vérifier que le secret a été capté, puis sauvegarde les codes de secours que l’écran suivant présente. Les codes apparaissent une seule fois — télécharge-les ou copie-les avant de cliquer sur **Terminé**. Le même écran porte **Désactiver** et **Régénérer les codes de secours**. Désactiver supprime le second facteur ; régénérer invalide chaque code de secours précédent. Les deux actions exigent le mot de passe du compte comme confirmation. ## Codes de secours Les codes de secours sont des chaînes à usage unique que la plateforme frappe quand la 2FA est activée ou régénérée. Chacun remplace le code authenticator sur une seule connexion — utile quand le téléphone est perdu, l’authenticator désinstallé, ou que tu es coincé quelque part sans l’appareil. La plateforme surveille le compte restant et affiche une bannière de niveau bas quand il ne reste que quelques codes ; la bannière renvoie directement au flux de régénération. Traite les codes de secours comme des mots de passe. Range-les dans un gestionnaire de mots de passe ou imprime-les et mets-les sous clé. Quiconque a ton mot de passe et un code de secours peut se connecter à ta place. ## Passkeys Un passkey est un identifiant WebAuthn — Face ID, Touch ID, Windows Hello ou une clé de sécurité matérielle — qui signe un défi à chaque connexion au lieu de produire un code à taper. L’identifiant est lié à l’origine du site : un domaine de phishing qui lui ressemble n’obtient rien à rejouer. Un passkey résiste donc au phishing d’une façon que TOTP n’atteint pas, et il satisfait une politique de deux facteurs appliquée exactement comme TOTP. Pour en enregistrer un, ouvre **Compte > Sécurité** et clique sur **Ajouter un passkey**. Donne à l’identifiant un nom que tu reconnaîtras plus tard, puis choisis le **Type d'authentificateur** : **Indifférent (recommandé)** laisse le navigateur proposer tout ce qui est disponible, **Cet appareil (Face ID, Touch ID, Windows Hello)** restreint la cérémonie à l’authentificateur intégré, et **Clé de sécurité ou téléphone** à un authentificateur itinérant. Le navigateur déroule la cérémonie d’enregistrement à partir de là. Chaque entrée de la même liste porte un bouton-icône **Supprimer** pour révoquer tes propres passkeys ; il demande une confirmation avant de supprimer le passkey. Un passkey enregistré fonctionne à trois portes. Sur l’écran de connexion, **Se connecter avec un passkey** te connecte sans taper le mot de passe — l’identifiant est lui-même une preuve forte. Sur l’écran de vérification après une connexion par mot de passe, **Utiliser un passkey à la place** remplace le code à six chiffres. Et sur l’écran d’inscription vers lequel une politique appliquée route les membres non inscrits, **Enregistrer un passkey à la place** se trouve à côté de la configuration TOTP — un membre qui n’enregistre qu’un passkey, jamais TOTP, passe la politique. Quand un membre perd un appareil qui porte un passkey, un Administrateur révoque l’identifiant : ouvre **Paramètres > Organisation**, clique sur **Modifier le membre** et supprime l’identifiant dans la section **Passkeys** du dialogue. Tale supprime l’identifiant et met fin à chaque session active du membre, donc un authentificateur perdu ou volé ne garde aucune session en vie. L’enregistrement, la suppression par soi-même, la révocation admin et chaque connexion par passkey atterrissent dans le journal d’audit (`passkey_added`, `passkey_removed`, `passkey_revoked_by_admin`, `passkey_sign_in`). ## La politique d’application pour l’org Les Administrateurs peuvent exiger le second facteur pour chaque membre authentifié par mot de passe de l’organisation. Ouvre **Paramètres > Gouvernance > Security & Monitoring** et, sous **Authentification à deux facteurs**, bascule **Exiger l'authentification à deux facteurs**. La politique porte une période de grâce (en jours) qui donne à chaque membre du temps pour s’inscrire à partir de sa première connexion sous la politique ; mets-la à zéro pour une application immédiate. <Frame caption="Gouvernance > Security & Monitoring — limites de tentatives de connexion et politique de mot de passe ; la politique d’authentification à deux facteurs se trouve plus bas sur la même page."> ![La page de gouvernance Security & Monitoring montrant les champs de limite de tentatives de connexion et les exigences de classes de caractères de la politique de mot de passe ; la politique de deux facteurs se trouve plus bas sur la même page.](/images/platform/governance-security-monitoring.webp) </Frame> | Champ | Type | Requis | Description | | ----------------------------------------- | ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ | | Exiger l’authentification à deux facteurs | Bascule | oui | Off garde la 2FA optionnelle pour chaque membre ; on active la politique. | | Période de grâce (jours) | Entier | oui | Jours à partir de la première connexion d’un membre sous la politique avant que l’inscription soit requise. Zéro veut dire immédiat. | | Exempter les utilisateurs SSO-seuls | Bascule | non | Quand on, les membres dont le seul compte est une identité fédérée s’appuient sur l’IdP en amont pour la MFA. | Un membre dans la fenêtre de grâce voit une bannière de compte à rebours dans l’appli qui pointe vers le flux d’inscription. Une fois la grâce expirée, la connexion suivante passe par l’écran d’inscription et le membre ne peut pas continuer tant qu’il n’est pas inscrit. ## Réinitialisation admin pour un membre verrouillé Quand un membre perd son téléphone et ses codes de secours, un Administrateur efface le second facteur sur son compte. Ouvre **Paramètres > Organisation**, clique sur **Modifier le membre** puis sur **Réinitialiser le double facteur** dans le dialogue. Tale désactive la 2FA pour le compte et met fin à chaque session active, donc le membre se réinscrit à sa prochaine connexion. La réinitialisation est enregistrée dans le journal d’audit sous `2fa_reset_by_admin`. Va vers ça comme action de récupération — le membre doit se réinscrire immédiatement une fois revenu. ## Où ça s’inscrit La 2FA est une couche au-dessus du mot de passe — même écran de connexion, deuxième étape. Combine-la avec [membres et rôles](/fr/platform/admin/members-and-roles) (l’admin qui réinitialise le second facteur est le même admin qui gère le compte), avec [politiques et limites](/fr/platform/admin/governance/policies-and-limits) (la politique d’application vit dans la surface gouvernance) et avec [journaux d’audit](/fr/platform/admin/governance/audit-logs) (chaque inscription, désactivation et réinitialisation admin y atterrit). # Sources de jetons Source: https://tale.dev/docs/fr/platform/admin/token-sources Paramètres > Sources de jetons sert au cas où une seule clé API statique ne suffit pas : au lieu de lier un agent bring-your-own-key à un secret unique, tu le branches sur un courtier externe qui renvoie un _pool_ d'identifiants. L'agent choisit un jeton par run et, si ce jeton revient bridé ou expiré, bascule sur un autre du même pool — jusqu'à trois tentatives avant l'échec du run. C'est la couche de rotation sous un [agent externe](/fr/platform/agents/external-agent) BYO, rien de plus : les agents managés continuent d'utiliser le gateway de l'org et ignorent entièrement cette page. Cette page couvre l'UI : ce que montre la liste, les champs quand tu ajoutes une source, comment une source se lie à un agent, et ce que fait vraiment la rotation au moment du run. Le secret d'auth du courtier est en écriture seule ici ; ses formes fichier et variable d'environnement vivent un onglet plus loin sous la référence de [configuration self-hosted](/fr/self-hosted/configuration/environment-reference). ## Ce que la liste montre Ouvre **Paramètres > Sources de jetons** et tu atterris sur le tableau des sources que l'org a configurées. Chaque ligne nomme la source, montre l'URL du point de terminaison de son courtier, et montre la variable d'environnement cible sous laquelle le moteur de rotation injecte le jeton choisi (pour un agent Claude Code c'est généralement `CLAUDE_CODE_OAUTH_TOKEN`). La recherche filtre par nom ou point de terminaison ; le menu **···** d'une ligne la modifie ou la supprime, et sélectionner des lignes fait apparaître une barre de suppression groupée. Une source n'est que de la config — elle stocke _comment_ joindre le courtier et _comment_ lire sa réponse, jamais les jetons eux-mêmes. Les jetons sont récupérés frais auprès du courtier à chaque démarrage de run d'agent, donc la liste ne se périme jamais face au pool courant du courtier. ## Ajouter une source Clique sur **Nouvelle source de jetons** et remplis le panneau latéral. Le formulaire est organisé en quatre sections : - **Identité** — un `Identifiant` (en minuscules, stable ; il nomme le fichier de config et le secret) et un nom affiché. - **Connexion** — l'**URL du point de terminaison** du courtier avec sa **Méthode HTTP**, et comment Tale s'authentifie _auprès du courtier_ : aucune, un jeton Bearer, ou un en-tête personnalisé. Pour Bearer ou en-tête tu saisis le secret du courtier. Le secret est en écriture seule — il n'est jamais renvoyé au navigateur, donc à la modification le champ apparaît vide et le laisser vide conserve la valeur stockée. - **Correspondance de la réponse** — comment lire le JSON du courtier. Le **Chemin des jetons** est un JSONPath vers le tableau de jetons (ex. `$.tokens`) ; le **Champ du jeton** nomme la propriété qui porte chaque jeton. Les **Champ de statut (facultatif)** / **Valeur de statut actif (facultatif)** filtrent les jetons inactifs, et le **Champ d'expiration (facultatif)** (un timestamp ISO ou des secondes/ms epoch) écarte ceux déjà expirés avant que le pool soit utilisé. - **Liaison** — la **Variable d'environnement cible** sous laquelle le jeton est injecté et la **Stratégie de sélection** : **Aléatoire** (le défaut, choisit uniformément par run) ou **Première** (déterministe). Avant d'enregistrer, appuie sur **Tester le courtier** dans la section Correspondance de la réponse : Tale interroge le courtier côté serveur avec la config en cours et prévisualise la correspondance — combien de jetons utilisables les chemins produisent, combien d'éléments ont été écartés comme inactifs, expirés ou sans champ de jeton, et la prochaine expiration. Un JSONPath erroné apparaît ainsi dans le formulaire plutôt qu'au moment du run de l'agent. Enregistrer valide la config, l'écrit, et rend la source immédiatement sélectionnable dans l'onglet Environnement de l'agent. ## Lier une source à un agent Une source de jetons ne fait rien tant qu'un agent n'y tire pas. Ouvre l'onglet **Environnement** de l'agent, ajoute une ligne, et change son type de **Valeur** / **Secret** vers **Source de jetons** — un second menu déroulant te laisse alors choisir quelle source. Le nom de variable de la ligne est la variable d'environnement où atterrit le jeton choisi, surchargeant le défaut propre à la source pour cet agent. La liaison ne prend effet que pour les agents bring-your-own-key. Un agent managé s'authentifie à travers le gateway de l'org, donc une ligne source de jetons sur l'un d'eux est ignorée avec un avertissement plutôt que de changer en silence comment l'agent est facturé. ## Ce que fait la rotation au moment du run Quand un agent BYO lié démarre, Tale récupère le pool du courtier, filtre les jetons inactifs et expirés, et injecte un choix. Si le run finit sur un échec rotatable — une erreur de débit (`429`/`529`) ou une erreur d'auth (`401`/`403`) — Tale échange un autre jeton du pool et relance, jusqu'à trois jetons au total, tant qu'il reste assez de la fenêtre du run. Une erreur d'auth est coupée court tôt plutôt que laissée à orager les retries internes du fournisseur. Si chaque jeton essayé échoue de la même façon, le run échoue vite avec une erreur claire au lieu de boucler. Si le courtier est injoignable, renvoie du JSON malformé, ou ne donne aucun jeton actif et non expiré, le run échoue immédiatement — il n'y a aucun fallback silencieux vers une clé statique, parce qu'un agent BYO n'en a aucune. ## Retirer une source Ouvre le menu **···** et choisis **Supprimer**, ou sélectionne des lignes et utilise la barre de suppression groupée. Supprimer retire la config et son secret stocké. Tout agent encore lié à la source supprimée échoue son prochain run avec une erreur de configuration plutôt que de basculer ailleurs, donc re-pointe ou retire la liaison dans l'onglet Environnement de l'agent d'abord. ## Où cela s'inscrit Les sources de jetons se tiennent à côté des [fournisseurs IA](/fr/platform/admin/providers) comme la seconde façon dont Tale acquiert des identifiants de modèle : les fournisseurs sont le chemin managé, routé par gateway ; les sources de jetons sont le chemin BYO, à rotation par courtier, pour les agents qui apportent leurs propres clés. La lecture suivante naturelle est la page [agent externe](/fr/platform/agents/external-agent) pour comment un agent BYO est construit, et la [référence des variables d'environnement](/fr/self-hosted/configuration/environment-reference) pour la forme `TALE_TOKEN_SOURCE_` du secret du courtier quand tu configures une source depuis des fichiers plutôt que l'UI. # SSO d’entreprise et provisionnement Source: https://tale.dev/docs/fr/platform/admin/enterprise-sso Le SSO d’entreprise permet à tes membres de se connecter via ton fournisseur d’identité (IdP) plutôt qu’avec un mot de passe Tale, et SCIM laisse l’IdP créer, mettre à jour et désactiver automatiquement les membres et les groupes — sans invitation manuelle. Une connexion par organisation porte ensemble le protocole de connexion, la politique de provisionnement et le jeton SCIM. Tout se trouve sur une seule page : **Paramètres > SSO d'entreprise** (administrateurs uniquement). Tale parle quatre protocoles : **OIDC**, **OAuth2** simple, **SAML 2.0** pour la connexion et **SCIM 2.0** pour le provisionnement. Tu peux activer la connexion, le provisionnement, ou les deux. <Frame caption="Paramètres > SSO d’entreprise — le sélecteur de protocole et les champs de connexion sur une page ; l’URL de redirection à enregistrer dans l’IdP, prête à copier."> ![La page de paramètres SSO d’entreprise avec le menu Protocole réglé sur Microsoft Entra ID et un nom d’affichage assorti, puis une section connexion qui porte l’URL de redirection à enregistrer, une URL d’émetteur et un ID client repris de l’enregistrement d’application, un secret client vide et les scopes demandés.](/images/platform/settings-enterprise-sso.webp) </Frame> ## Choisir un protocole Ouvre **Paramètres > SSO d'entreprise**, choisis un **Protocole** et remplis uniquement les champs de ce protocole — les autres restent masqués. Un **Guide de configuration** sur la même page liste les étapes exactes et affiche les URL à coller dans ton IdP. Utilise **Tester la connexion** avant d’enregistrer pour valider la configuration, et **Enregistrer** pour activer la connexion. - **Microsoft Entra ID** — l’OIDC de Microsoft, avec synchronisation groupe-vers-équipe via Microsoft Graph. - **OIDC générique** — n’importe quel fournisseur OpenID Connect (Google, Okta, Auth0, Keycloak, …). Les points de terminaison sont détectés depuis l’émetteur. - **OAuth2** — fournisseurs sans découverte OIDC ; tu configures manuellement les points de terminaison d’autorisation, de jeton et userinfo. - **SAML 2.0** — SSO basé sur XML ; tu échanges des métadonnées avec l’IdP. ## Microsoft Entra ID 1. Connecte-toi au [centre d’administration Microsoft Entra](https://entra.microsoft.com) en tant que développeur d’applications au minimum. 2. Va dans **Entra ID > Inscriptions d'applications > Nouvelle inscription**, nomme-la et choisis **Locataire unique**. 3. Sous **URI de redirection**, sélectionne la plateforme **Web**, colle l'**URL de redirection** affichée sur la page Tale, puis clique sur **Inscrire**. 4. Sur la **Vue d'ensemble**, copie l'**ID d'application (client)** et l'**ID de répertoire (locataire)**. Ton URL d’émetteur est `https://login.microsoftonline.com/{tenant-id}/v2.0`. 5. Ouvre **Certificats et secrets > Nouveau secret client** et copie la **Valeur** du secret (pas son ID). 6. Dans Tale, choisis **Microsoft Entra ID** et saisis l’ID client, le secret client et l’URL d’émetteur. 7. Pour la synchronisation groupe-vers-équipe, ajoute l’autorisation Microsoft Graph **GroupMember.Read.All** sous **Autorisations d'API** et accorde le consentement administrateur. 8. Pour la synchronisation de documents OneDrive et SharePoint, ajoute les autorisations Microsoft Graph **Files.Read** et **Sites.Read.All** sous **Autorisations d'API** et accorde le consentement administrateur. Une nouvelle connexion demande les deux par défaut — le token SSO sert aussi de token Graph, les membres peuvent donc importer des fichiers dès la connexion. Si l’organisation ne veut que la connexion, retire ces deux scopes du champ **Scopes** ; l’entrée Microsoft 365 reste alors masquée sur la page des documents. ## Google Google se configure comme un fournisseur OIDC générique. 1. Dans la [console Google Cloud](https://console.cloud.google.com), ouvre **API et services > Identifiants > Créer des identifiants > ID client OAuth**. 2. Choisis le type d’application **Application Web**. 3. Sous **URI de redirection autorisés**, ajoute l'**URL de redirection** affichée sur la page Tale, puis enregistre. 4. Copie l'**ID client** et le **secret client** en haut de la page du client. 5. Dans Tale, choisis **OIDC générique**, saisis l’ID client et le secret, et définis l’URL d’émetteur sur `https://accounts.google.com`. Les points de terminaison sont détectés automatiquement. L’OIDC standard de Google ne renvoie **pas** les appartenances aux groupes : la synchronisation groupe-vers-équipe n’est donc pas disponible avec Google seul — elle nécessite l’Admin SDK / l’API Cloud Identity avec un administrateur Workspace. La connexion et le mappage de rôle par claim fonctionnent normalement. ## OIDC générique et OAuth2 Pour tout autre fournisseur OIDC (Okta, Auth0, Keycloak), choisis **OIDC générique**, colle l'**URL d'émetteur** et l’ID/secret client — Tale lit les points de terminaison d’autorisation, de jeton et userinfo depuis le `.well-known/openid-configuration` de l’émetteur. Si un fournisseur expose OAuth2 mais pas de document de découverte, choisis **OAuth2** et saisis manuellement les URL des points de terminaison d'**autorisation**, de **jeton** et **userinfo**. Lorsque le fournisseur utilise des noms de claims non standard, mappe **e-mail**, **nom** et **groupes** dans les champs avancés de la connexion (les chemins en points sont pris en charge, p. ex. `realm_access.roles`). ## SAML 2.0 1. Dans Tale, choisis **SAML 2.0**. La page affiche ton **URL des métadonnées SP** et ton **URL ACS (réponse)** — copie-les. 2. Dans ton IdP, crée une nouvelle application SAML 2.0. Définis son **URL ACS** et son **Entity ID / Audience** sur les valeurs SP affichées (ou importe l’URL des métadonnées SP), et le format **Name ID** sur l’adresse e-mail. 3. Sous **Importer les métadonnées de l'IdP**, colle l’URL des métadonnées de fédération de ton IdP et clique sur **Importer** — ou clique sur **Téléverser le XML** si ton IdP ne propose qu’un fichier à télécharger. Tale lit les métadonnées et remplit l’ID d’entité, l’URL de connexion et le certificat de signature dans les champs ci-dessous, sans que tu aies à les ressaisir. Les trois champs restent modifiables — vérifie les valeurs importées (ou saisis-les toi-même si ton IdP ne publie aucune métadonnée) avant d’enregistrer. 4. Mappe les attributs **e-mail**, **nom** et **groupe** dans ton IdP ; si leurs noms diffèrent des valeurs par défaut, indique les noms d’attributs correspondants dans les champs avancés de Tale. Tale prend en charge le SAML initié par l’IdP (l’IdP envoie une assertion à l’URL ACS) et le SAML initié par le SP (un membre clique sur **Se connecter avec le SSO** et Tale redirige vers l’IdP). Les assertions signées sont requises ; les assertions chiffrées sont prises en charge si tu fournis une paire de clés SP. ## Plusieurs organisations sur un même déploiement Un déploiement peut héberger plusieurs organisations, chacune avec sa propre connexion. Sur la page de connexion, clique sur **Continuer avec SSO**, puis choisis ton organisation dans la liste — chaque entrée affiche le **Nom affiché** de la connexion. Ce nom est visible par quiconque sur la page de connexion ; définis un nom clair par connexion dans **Paramètres > Enterprise SSO**. ## Provisionnement : rôles et équipes Chaque protocole partage une politique de provisionnement : - **Rôle par défaut** — le rôle attribué à un membre nouvellement provisionné (Membre par défaut). - **Attribution automatique des rôles** — lorsqu’il est activé, des règles de mappage associent un intitulé de poste, un rôle d’application, un groupe ou un claim à un rôle de la plateforme ; le rôle par défaut s’applique si rien ne correspond. - **Synchroniser les groupes en équipes** — lorsqu’il est activé, chaque groupe IdP de l’utilisateur devient (ou rejoint) une équipe du même nom à la connexion ; **Exclure des groupes** ignore les groupes parasites (séparés par des virgules). ## Provisionnement SCIM (utilisateurs et groupes) SCIM permet à ton IdP de transmettre les changements sans que personne ne se connecte. Dans la section **Provisionnement SCIM**, clique sur **Générer un jeton** — copie-le une seule fois (il n’est plus jamais affiché) — et colle-le, avec l'**URL de base SCIM** affichée, dans les paramètres de provisionnement de ton IdP. L’IdP s’authentifie avec le jeton comme identifiant Bearer ; Tale détermine l’organisation à partir du jeton, qui constitue donc la frontière de locataire. Tale implémente SCIM 2.0 **Users** et **Groups** : créer, lire, lister (avec filtres `userName`/`displayName`), remplacer, modifier (patch) et supprimer. Les utilisateurs provisionnés correspondent à des membres de l’organisation, les groupes à des équipes. **La désactivation est douce** — lorsque l’IdP rend un utilisateur inactif (`active: false`), le rôle du membre passe à `disabled` (ce qui retire son accès), et une réactivation restaure son rôle précédent. Une **suppression** SCIM retire l’appartenance à l’organisation ; le compte utilisateur est conservé, et un nouveau provisionnement le rattache avec le rôle par défaut de la connexion. Le propriétaire de l’organisation ne peut jamais être déprovisionné via SCIM. ## Vérification Utilise **Tester la connexion** pour OIDC/OAuth2 afin de confirmer la découverte et les identifiants avant d’enregistrer. Pour SAML, importe les métadonnées SP dans ton IdP et effectue une connexion de test. Pour SCIM, la plupart des IdP proposent une action « test » ou « provisionner maintenant » qui crée un utilisateur d’exemple — vérifie qu’il apparaît sous **Paramètres > Membres**. Une connexion SSO de bout en bout se vérifie au mieux contre ton IdP réel dans une organisation de préproduction. # Catalogue de modèles Source: https://tale.dev/docs/fr/platform/models Chaque sélecteur de modèle dans Tale — le menu de modèle du composeur, la liaison de modèle d’un agent, les défauts qu’utilisent les services de crawl et de RAG — puise dans un seul catalogue : les modèles déclarés sur les fournisseurs d’IA de ton organisation. Une instance toute neuve embarque un seul fournisseur, **OpenRouter**, dont l’unique clé couvre le chat, la vision, les embeddings, la transcription, la synthèse vocale et la génération d’images. Cette page est la référence pour savoir où vit ce catalogue dans l’UI, ce que veulent dire les étiquettes sur chaque modèle, et ce qui est livré en standard. <Frame caption="La liste de modèles du tiroir fournisseur — chaque modèle porte les étiquettes de capacité qui décident dans quels sélecteurs il apparaît."> ![Le tiroir de détails du fournisseur sous Paramètres > Providers, montrant une liste de modèles cherchable où chaque ligne porte des étiquettes de capacité comme Chat et Génération d’images, avec les actions Récupérer les modèles, Synchroniser depuis le catalogue et Ajouter un modèle au-dessus.](/images/platform/settings-provider-models.webp) </Frame> ## Où vit le catalogue Ouvre **Paramètres > Providers** et clique sur une ligne de fournisseur. Le tiroir liste tout ce que le fournisseur déclare : son URL de base et sa clé API, ses **Modèles par défaut**, et la liste **Modèles** elle-même — cherchable, avec **Afficher plus** après les dix premiers. **Ajouter un modèle** déclare une nouvelle entrée à la main ; **Récupérer les modèles** tire la liste que l’API du fournisseur rapporte. Les modèles qu’un admin marque **Masqué des sélecteurs de modèles** restent résolvables pour les liaisons existantes mais cessent d’apparaître dans les menus — c’est ainsi que les versions supplantées prennent leur retraite sans casser les anciens agents. Chaque modèle porte une ou plusieurs étiquettes de capacité : **Chat**, **Vision**, **Embedding**, **Transcription**, **Synthèse vocale**, **Génération d'images**, **Édition d'images**. Les étiquettes sont porteuses — elles décident dans quels sélecteurs un modèle apparaît et quelle capacité de la plateforme a le droit de l’appeler. Un modèle sans étiquette correspondante n’apparaît jamais là où cette capacité est requise. ## Les défauts livrés La carte **Modèles par défaut** nomme quel modèle chaque capacité d’arrière-plan utilise quand rien de plus spécifique n’est lié : | Capacité | Défaut livré | | ------------------- | ------------------ | | Chat | DeepSeek V4 Flash | | Vision | Qwen3 VL 32B | | Embedding | Qwen3 Embedding 8B | | Génération d’images | FLUX.2 [pro] | | Transcription | Whisper v1 | La synthèse vocale pour le [mode vocal](/fr/platform/chat/voice-mode) est livrée via le GPT-4o mini TTS d’OpenAI à travers la même clé OpenRouter, et la [génération d’images](/fr/platform/agents/image-generation) retombe sur FLUX.2 [pro]. ## Comment la liste reste à jour Les modèles dérivent plus vite que la doc. Deux mécanismes sur la page **Providers** gardent le catalogue à jour : la carte **Catalogue de modèles** rafraîchit les capacités des modèles — tarification, fenêtre de contexte, raisonnement, vision — depuis le catalogue public d’OpenRouter chaque jour, et la bascule **Auto-sync hebdomadaire de la config fournisseur** fusionne les nouvelles versions phares une fois par semaine dans la config fournisseur de l’org, masque les versions supplantées et laisse intact tout champ que tu as personnalisé. La liste livrée ci-dessous est régénérée depuis la même source, elle correspond donc à ce que voit une instance toute neuve : <!-- MODELS_TABLE:START --> <!-- Auto-generated from builtin-configs/providers/openrouter.json by the weekly model-catalog sync. Do not edit by hand. --> | Fournisseur | Modèle | Capacités | Contexte | Entrée ($/M) | Sortie ($/M) | | ----------------- | ------------------------------------ | ---------------------------- | -------- | ------------ | ------------ | | AI21 | Jamba Large 1.7 | chat | 256K | 2.00 | 8.00 | | Amazon | Nova Premier | chat, vision | 1M | 2.50 | 12.50 | | Amazon | Nova 2 Lite | chat, vision | 1M | 0.30 | 2.50 | | Anthropic | Claude Fable (latest) | chat, vision | 1M | 10.00 | 50.00 | | Anthropic | Claude Fable 5 | chat, vision | 1M | 10.00 | 50.00 | | Anthropic | Claude Sonnet 4.6 | chat, vision | 1M | 3.00 | 15.00 | | Anthropic | Claude Haiku 4.5 | chat | 200K | 1.00 | 5.00 | | Anthropic | Claude Opus 4.8 | chat, vision | 1M | 5.00 | 25.00 | | Black Forest Labs | FLUX.2 [flex] | image-generation, image-edit | — | — | — | | Black Forest Labs | FLUX.2 [max] | image-generation, image-edit | — | — | — | | Black Forest Labs | FLUX.2 [pro] | image-generation, image-edit | — | — | — | | Cohere | Command A | chat | 256K | 2.50 | 10.00 | | Cohere | Command R | chat | 128K | 0.15 | 0.60 | | DeepSeek | DeepSeek V4 Pro | chat | 1M | 0.43 | 0.87 | | DeepSeek | DeepSeek V4 Flash | chat | 1M | 0.09 | 0.18 | | Google | Gemini 3 Pro | chat, vision | 1M | 2.00 | 12.00 | | Google | Gemini 3 Flash | chat, vision | 1M | 0.50 | 3.00 | | Google | Gemma 4 31B IT | chat, vision | 262K | 0.12 | 0.35 | | Google | Gemma 4 26B A4B IT | chat, vision | 262K | 0.06 | 0.33 | | Google | Nano Banana (Gemini 2.5 Flash Image) | image-generation, image-edit | 33K | 0.30 | 2.50 | | Liquid | LFM2 24B | chat | 128K | 0.03 | 0.12 | | Meta | LLaMA 4 Maverick | chat | 1M | 0.15 | 0.60 | | Meta | LLaMA 4 Scout | chat | 10M | 0.10 | 0.30 | | Microsoft | Phi-4 | chat | 16K | 0.07 | 0.14 | | MiniMax | MiniMax M3 | chat, vision | 1M | 0.30 | 1.20 | | Mistral | Mistral Large 3 | chat | 262K | 0.50 | 1.50 | | Mistral | Mistral Medium 3.5 | chat, vision | 262K | 1.50 | 7.50 | | Moonshot AI | Kimi K2.6 | chat, vision | 262K | 0.68 | 3.41 | | Moonshot AI | Kimi K2.7 Code | chat, vision | 262K | 0.61 | 3.07 | | NVIDIA | Nemotron 3 Ultra | chat | 1M | 0.50 | 2.20 | | NVIDIA | Nemotron 3 Super | chat | 1M | 0.09 | 0.45 | | OpenAI | GPT-OSS 120B | chat | 131K | 0.04 | 0.18 | | OpenAI | GPT-4o mini TTS | text-to-speech | — | — | — | | OpenAI | GPT-5.3 Chat | chat, vision | 128K | 1.75 | 14.00 | | OpenAI | GPT-5.5 | chat, vision | 1M | 5.00 | 30.00 | | OpenAI | GPT-5.5 Pro | chat, vision | 1M | 30.00 | 180.00 | | OpenAI | Whisper v1 | transcription | — | — | — | | Perplexity | Sonar Pro | chat, vision | 200K | 3.00 | 15.00 | | Perplexity | Sonar | chat, vision | 127K | 1.00 | 1.00 | | Qwen | Qwen3.6 Max Preview | chat | 262K | 1.04 | 6.24 | | Qwen | Qwen3 Coder 480B | chat | 1M | 0.22 | 1.80 | | Qwen | Qwen3 VL 32B | chat, vision | 262K | 0.10 | 0.42 | | Qwen | Qwen3.6 Flash | chat, vision | 1M | 0.19 | 1.13 | | Qwen | Qwen3 Embedding 8B | embedding | — | 0.01 | 0.00 | | Qwen | Qwen3.7 Plus | chat, vision | 1M | 0.32 | 1.28 | | Reka | Reka Flash 3 | chat | 66K | 0.10 | 0.20 | | Xiaomi | MiMo V2.5 Pro | chat | 1M | 0.43 | 0.87 | | Z.AI | GLM 5.1 | chat | 203K | 0.98 | 3.08 | | Z.AI | GLM 5 Turbo | chat | 262K | 1.20 | 4.00 | | Z.AI | GLM 5V Turbo | chat, vision | 131K | 1.20 | 4.00 | | xAI | Grok 4.20 | chat, vision | 2M | 1.25 | 2.50 | <!-- MODELS_TABLE:END --> Le catalogue complet et en direct vit sur [openrouter.ai/models](https://openrouter.ai/models) ; n’importe quel modèle qu’OpenRouter expose peut être ajouté à ton instance depuis le même tiroir. ## Où cela s’inscrit Les modèles sont la couche sous chaque agent, chaque réponse de chat, chaque sortie vocale et chaque image que la plateforme rend. OpenRouter est le défaut, pas une obligation — ajouter un fournisseur direct, un serveur Ollama ou vLLM local, ou une seconde passerelle est du travail d’admin couvert par [Providers](/fr/platform/admin/providers), et la forme basée fichier de la même configuration vit sous [Configuration → providers](/fr/self-hosted/configuration/providers). Pour choisir entre des modèles de chat quand plus d’un pourrait faire le travail, [Mode arène](/fr/platform/chat/arena-mode) est le workflow bâti exactement pour cette question. # Éditeur Source: https://tale.dev/docs/fr/platform/editor/overview Éditeur est la surface de construction de Tale. Là où Membre est le rôle qui utilise le produit et Administrateur le rôle qui le gouverne, Éditeur est le rôle qui crée les choses que tout le monde consomme — agents, projets, automatisations, les documents et données structurées que tient la base de connaissances, les prompts enregistrés pour l’équipe. Les personnes de rôle Éditeur voient l’ensemble complet d’onglets de construction sans la surface gouvernance admin et sans les leviers réservés aux développeurs. Cette vue d’ensemble nomme ce que fait un Éditeur, où il le fait, et quelles pages couvrent chaque pièce. Les Éditeurs atterrissent typiquement ici à leur premier jour, construisent le premier agent et projet utile de l’org, et reviennent sur cet onglet chaque fois que la prochaine chose doit être bâtie. L’histoire des rôles et permissions derrière les onglets vit sur [Membres et rôles](/fr/platform/admin/members-and-roles). ## Ce que couvre Éditeur Le travail d’un Éditeur tombe dans quatre seaux : construire des **agents** (instructions, liaisons de connaissance, tools, modèles), curer la **base de connaissances** (téléverser des documents, maintenir clients, produits, fournisseurs, sites web), écrire des **automatisations** (workflows avec déclencheurs, étapes, gates d’approbation), et empaqueter des **projets** (jeux de fichiers, agents cadrés, instructions de projet). Chaque seau a sa propre section dans Platform ; l’onglet Éditeur est l’index à travers. Les Éditeurs partagent la surface de construction avec les Développeurs — les Développeurs voient aussi les quatre seaux et peuvent tout ce qu’un Éditeur peut, plus le plan API et intégrations. Va vers un Éditeur quand le travail quotidien est contenu et configuration ; va vers un Développeur quand le travail croise le code ou les systèmes externes. ## Pages dans cette section La surface Éditeur est la même surface que documentent les sections par domaine de Platform. Ce qui suit est l’index à travers. <CardGroup cols="2"> <Card title="Agents" icon="bot" href="/fr/platform/agents/concepts"> Le modèle mental à quatre boutons à partir duquel un Éditeur construit chaque agent. </Card> <Card title="Automatisations" icon="workflow" href="/fr/platform/automations/concepts"> Workflows, déclencheurs, étapes, exécutions. </Card> <Card title="Connaissance" icon="library" href="/fr/platform/knowledge/overview"> La zone documents-et-données-structurées qu’un Éditeur cure. </Card> <Card title="Projets" icon="folder-open" href="/fr/platform/projects/overview"> L’espace de travail partagé qu’un Éditeur empaquette autour d’un client ou d’un lancement. </Card> <Card title="Bibliothèque de prompts" icon="list-plus" href="/fr/platform/workspace/prompt-library"> La zone de prompts enregistrés qu’un Éditeur utilise pour garder les amorces de chat récurrentes réutilisables. </Card> </CardGroup> ## Où cela s’inscrit Éditeur est le rôle dont la plupart des équipes ont plusieurs — les personnes qui font le travail de construction que les autres rôles consomment. La première lecture naturelle au jour un est [Concepts agents](/fr/platform/agents/concepts), parce que le modèle à quatre boutons est ce que chaque autre page de construction présuppose. La seconde naturelle est [Construire ton premier agent](/fr/tutorials/editor/first-agent-end-to-end) — elle parcourt les quatre boutons de bout en bout sur une instance fraîche. # Architecture auto-hébergée Source: https://tale.dev/docs/fr/self-hosted/overview Une instance Tale, ce sont huit conteneurs derrière un proxy Caddy, parlant à deux bases Postgres — une opérationnelle, une pour le corpus de connaissances ; deux d'entre eux sont des conteneurs sandbox sur le côté pour l'exécution de code. Le fichier compose est le contrat — ce qui tourne, ce qui est exposé, ce qui est monté. Cette page te donne le modèle mental pour que les pages installation, configuration et exploitation n'aient pas à le réexpliquer. Lis ceci avant de `docker compose up`. Reviens-y quand tu débogues un incident et que tu dois savoir quel log de conteneur ouvrir en premier. ## Les huit conteneurs **tale-proxy** est Caddy en bordure. Il termine TLS, route tout sous `/` vers le conteneur plateforme, et tout sous `/api/` et les chemins Convex vers le conteneur convex. Les healthchecks vivent ici. **tale-platform** est le serveur React + TanStack Start. Il rend l'UI, sert les assets statiques et est le seul conteneur exposé au navigateur. Il ne porte pas d'état métier — tout ce qui doit persister parle à convex. **tale-convex** est le backend : les actions, queries, mutations et la couche WebSocket à laquelle l'UI s'abonne. Clés de fournisseur, définitions d'agent, exécutions de workflow, journaux d'audit — tout cela vit ici. Il exécute aussi le travail de connaissances en in-process — l'ingestion de documents, le crawling web, la recherche RAG et la génération de documents sont des node-actions Convex, pas des services séparés. Le travail headless dont ces tâches ont besoin (rendre une page web, transformer du HTML en PDF ou en image) est délégué au runtime sandbox, qui embarque déjà Chromium et Playwright. **tale-db** est le Postgres opérationnel (ParadeDB). Il porte les données du backend Convex — agents, runs, le log d'audit — et est l'un des deux conteneurs stateful qui comptent pour les sauvegardes. **tale-knowledge-db** est le Postgres du corpus de connaissances (ParadeDB), la base `tale_knowledge` avec deux schémas : `private_knowledge` (fragments de documents téléversés, embeddings, index BM25, cache sémantique) et `public_web` (pages web crawlées). Il est séparé de `tale-db` pour que le corpus — la banque sensible à la résidence des données — puisse être relocalisé ou remplacé tout seul. Le backend Convex s'y connecte directement ; rien d'autre ne le fait. **tale-sandbox-llm-gateway** est la gateway LLM pour les agents de code en sandbox. C'est le seul chemin d'un agent en sandbox vers un fournisseur de modèles ; la plateforme le provisionne et frappe des clés par session. **tale-sandbox** et **tale-sandbox-egress** exécutent du code en sandbox pour le compte de l'outil **Exécuter du code** et des scripts de compétence, et servent de runtime de navigateur headless que le backend convex appelle pour le rendu web et la génération de documents. Le conteneur egress est le seul chemin que la sandbox a vers le réseau. L'egress est ouvert par défaut — le code en sandbox atteint n'importe quel hôte public en HTTPS, tandis que les métadonnées cloud et les plages d'adresses privées restent bloquées au niveau IP ; restreins-le à une allowlist d'hôtes avec `SANDBOX_EGRESS_ALLOWLIST`, décrite dans [Durcissement](/fr/self-hosted/operate/security/hardening). Un service de plus est livré mais reste éteint par défaut : **tale-controller** est un sidecar à activer explicitement (le profil compose `controller`) qui redémarre le conteneur convex sur une requête signée venant de l'app, pour qu'un changement de résidence des données s'applique sans donner à la plateforme exposée au navigateur l'accès au socket Docker. ## Données sur le disque Quatre volumes survivent à un `docker compose down` : - `db-data` — le répertoire de données du Postgres opérationnel : la base derrière les agents, les runs et le log d'audit. - `knowledge-db-data` — le répertoire de données du Postgres du corpus de connaissances : fragments de documents, embeddings, index de recherche et pages web crawlées. Se sauvegarde séparément de `db-data` parce que c'est une base distincte. - `backups` — snapshots de volumes checksummés, écrits par `tale backup` et automatiquement avant les déploiements migrants ; [Backups et restauration](/fr/self-hosted/operate/backups-and-restore) est le drill. - Le montage du magasin d'objets Convex — fichiers téléversés, documents générés, bundles exportés. Tout le reste est éphémère. Les conteneurs peuvent être remplacés sans perte de données tant que les volumes survivent. ## Secrets de fournisseur et couche SOPS Les clés de fournisseur (OpenAI, Anthropic, Azure, Ollama, etc.) vivent sur le disque dans un répertoire `providers/` monté dans le conteneur plateforme. Chaque fournisseur a un `<nom>.json` et un `<nom>.secrets.json` ; le fichier secrets est chiffré avec SOPS et la variable [`SOPS_AGE_KEY`](/fr/self-hosted/configuration/environment-reference). Cette séparation existe pour deux raisons. Faire tourner une clé de fournisseur, c'est éditer un fichier, pas redémarrer la plateforme ; sauvegarder le fichier chiffré est sûr à committer aux côtés de l'infrastructure. Le mode clair (pas de SOPS, secrets en clair) est supporté pour des environnements étroitement contrôlés où le disque lui-même est chiffré au repos. ## Auth et sessions Le sign-in est Better Auth tournant dans le conteneur convex. Quatre modes de sign-in sont fournis : mot de passe local, Microsoft Entra (OAuth/OIDC), OIDC générique et trusted headers (le reverse proxy fournit l'identité). Le conteneur plateforme lit le cookie, le passe à convex, et convex décide de ce que la session peut faire sur la base du rôle de l'utilisateur et de la matrice de permissions par ressource documentée dans [Membres et rôles](/fr/platform/admin/members-and-roles). La [référence d'authentification](/fr/self-hosted/configuration/authentication) couvre les variables d'environnement et les arbitrages par mode. ## Quand tu sors du single-host Le fichier compose par défaut fait tourner les huit conteneurs sur un hôte. L'architecture est mono-tenant : rien dans le design ne répartit le travail entre hôtes. La première chose que tu peux sortir de la boîte sans réarchitecturer, c'est le corpus de connaissances — `tale-knowledge-db` est un Postgres autonome, donc le pointer vers une infrastructure gérée (pour la capacité ou pour une exigence de résidence) est un changement de chaîne de connexion, couvert dans [Résidence des données](/fr/self-hosted/configuration/data-residency). La couche Convex reste mono-instance ; la scalabilité horizontale du backend n'est pas une fonctionnalité v1. ## Où cela s'inscrit Cette page d'architecture est la carte que présuppose chaque autre page auto-hébergée. La lecture suivante naturelle est [Quickstart](/fr/self-hosted/install/quickstart) si tu montes une instance neuve, ou [Architecture des conteneurs](/fr/self-hosted/operate/container-architecture) si tu en exploites une et que tu veux la même image superposée aux modes de défaillance. # Auto-hébergé Source: https://tale.dev/docs/fr/self-hosted Tale auto-hébergé tourne sur ta propre infrastructure — on-premise, dans ton VPC, ou coupé du réseau. Sept conteneurs, tes données sur ton stockage, aucune facturation au siège, et aucun trafic qui rejoint les serveurs de Tale, sauf si tu y pointes un fournisseur. Cette section s'adresse aux opérateurs : les personnes qui décident où Tale tourne, l'installent, le configurent, le maintiennent à jour et récupèrent le pager quand quelque chose va de travers. Les utilisateurs finaux des instances auto-hébergées lisent surtout l'onglet Plateforme — la surface produit est identique entre les éditions. ## Pages de cette section **[Vue d'ensemble de l'architecture](/fr/self-hosted/overview)** — ce que fait chaque conteneur, où vivent les données sur le stockage, qui parle à qui. **[Installation](/fr/self-hosted/install/quickstart)** — quickstart sur portable, installation de production sur un hôte Linux, la référence docker compose, premier admin, l'installateur du CLI. **[Configuration](/fr/self-hosted/configuration/environment-reference)** — chaque variable d'environnement, fichiers de fournisseur, modes d'authentification, TLS, stockage, rétention, secrets chiffrés par SOPS, observabilité. **[Exploitation](/fr/self-hosted/operate/container-architecture)** — montées de version, sauvegardes et restauration, observabilité et dépannage, avis de sécurité, durcissement, format des notes de version. **[Contribuer](/fr/self-hosted/contributing-docker)** — comment construire et tester une modification locale de conteneur. ## Où cela s'inscrit Auto-hébergé est l'édition où l'opérateur possède davantage de la stack. Si ton équipe est petite et que la charge d'exploitation écraserait le travail produit, [Cloud](/fr/cloud) est l'autre forme du même produit. Si tu montes une instance neuve maintenant, [Quickstart](/fr/self-hosted/install/quickstart) est la lecture suivante adéquate. # Contribuer aux images Docker Source: https://tale.dev/docs/fr/self-hosted/contributing-docker Chaque conteneur que Tale ship a son Dockerfile dans le repo source public. Les forks, distributions air-gapped et patches one-off partent tous des mêmes fichiers ; cette page est le walk opérateur à travers la construction des images toi-même, où les coutures de personnalisation vivent, et comment garder un fork en sync avec l'amont sans diverger sur les parties ennuyeuses. L'architecture des conteneurs vit dans [Architecture des conteneurs](/fr/self-hosted/operate/container-architecture) ; cette page est ce que tu lis quand les images publiées ne vont pas et qu'il te faut construire les tiennes. ## Quelles sont les images La stack est entièrement TypeScript — pas d'image Python. Chaque image a un Dockerfile sous `services/<name>/` : | Image | Chemin source | Base | | ------------------------ | ----------------------------- | ---------------------------- | | `tale-proxy` | `services/proxy/` | Caddy | | `tale-platform` | `services/platform/` | Bun + Debian slim | | `tale-convex` | `services/convex/` | Convex local-backend | | `tale-db` | `services/db/` | ParadeDB (Postgres) | | `tale-sandbox` | `services/sandbox/` | Bun + CLI Docker | | `tale-sandbox-egress` | `services/sandbox-egress/` | Alpine + tinyproxy | | `tale-sandbox-runtime` | `services/sandbox-runtime/` | Bun + Chromium + Playwright | | `tale-sandbox-buildkitd` | `services/sandbox-buildkitd/` | Debian + BuildKit + redsocks | | `tale-controller` | `services/controller/` | Bun + CLI Docker | Les deux conteneurs de base de données — `db` et `knowledge-db` — se construisent depuis la même image ParadeDB `tale-db` ; la différence est la base que chacun sert. La gateway LLM, `tale-sandbox-llm-gateway`, est une image amont pinnée (`maximhq/bifrost`), elle n'a donc pas de Dockerfile dans le repo. Les fichiers compose à la racine du repo (`compose.yml` pour développement, le compose de production généré par la CLI) les référencent via `ghcr.io/tale-project/tale/<image>:<tag>`. Un build local remplace le pull de registre par un bloc `build:` dans compose. ## Construire localement Un premier build de chaque image prend environ 15 minutes sur un laptop récent ; les builds suivants touchent le cache de layers de Docker et finissent en moins d'une minute pour l'image que tu as changée. ```bash # Construis chaque image dans compose.yml docker compose build # Construis une image docker compose build platform ``` Mets `PULL_POLICY=build` dans ton environnement (ou dans `.env`) pour forcer compose à construire plutôt qu'à puller l'image publiée. Le `compose.yml` livré défaut sur `build`, donc un clone local sans overrides construit déjà ; les fichiers compose de production que `tale deploy` génère défautent sur `always` et pullent depuis le registre. ## Les coutures de personnalisation Les points d'extension supportés pour les forks sont au niveau du Dockerfile. L'entrypoint de l'image et les fichiers de configuration à l'intérieur sont stables — patche-les, construis l'image, et le reste du système n'a pas besoin de savoir. - **Caddyfile** — `services/proxy/Caddyfile` contrôle le routage et la terminaison TLS. Les en-têtes personnalisés, sous-domaines personnalisés et rate limits personnalisés atterrissent ici. - **Templates plop plateforme** — `services/platform/Dockerfile` lance une étape de build qui cuit les messages, le schéma et les assets statiques. Un fork qui ship des chaînes UI personnalisées ou des routes supplémentaires construit l'image plateforme. - **Image runtime sandbox** — `services/sandbox-runtime/Dockerfile` est l'environnement d'exécution pour **Exécuter du code**, le rendu web et la génération de documents ; il embarque déjà Chromium et Playwright. Un fork qui a besoin d'un paquet système supplémentaire ou d'un build de navigateur différent patche ici. - **Proxy d'egress sandbox** — `services/sandbox-egress/tinyproxy.conf.template` est la configuration proxy que l'entrypoint rend au démarrage : egress ouvert par défaut, ou un filtre d'hôtes en refus par défaut quand `SANDBOX_EGRESS_ALLOWLIST` est défini. Un fork qui a besoin d'un autre comportement proxy patche ici. Ce qui n'est pas une couture supportée : le code applicatif du backend convex, y compris l'extraction de documents et la logique RAG et crawler qui vit désormais en in-process (`services/platform/convex/`), et le code runtime du conteneur plateforme (`services/platform/app/`). Ces fichiers sont du code applicatif, pas de la configuration — ajouter un extracteur de format de document ou changer le comportement de récupération est un vrai fork et porte la taxe de montée de version. ## Tagger et pousser vers ta propre registre Pour les distributions air-gapped ou vendorisées, le chemin est « construire, tagger, pousser vers ta registre, changer les lignes `image:` du compose ». ```bash # Construire, tagger, pousser export REGISTRY=registry.internal.example.com/tale docker compose build docker tag ghcr.io/tale-project/tale/tale-platform:latest \ $REGISTRY/tale-platform:vendored-1.0 docker push $REGISTRY/tale-platform:vendored-1.0 ``` Le déploiement de la CLI génère un fichier compose avec le chemin de registre ; soit patche le fichier généré après génération, soit saute la CLI et lance `docker compose` directement contre un fichier compose que tu maintiens toi-même. ## Rester en sync avec l'amont Le chemin bon marché est un fork sur GitHub qui merge périodiquement depuis `tale-project/tale@main`. Les conflits atterrissent dans les fichiers que tu as patchés ; le reste passe propre. Les deux anti-patterns : - **Patcher du code applicatif au lieu de le contribuer en retour.** Si le changement est largement utile, upstream une PR — chaque taxe de release descend. - **Pinner sur une vieille image de base.** Les bases Caddy, Bun et Postgres prennent les patches de sécurité à la reconstruction ; pinner la base pour la « stabilité » est emprunter des ennuis. ## Où cela s'inscrit Cette page est la couture côté contributeur de l'histoire opérateur. La vue d'ensemble de l'architecture vit dans [Architecture des conteneurs](/fr/self-hosted/operate/container-architecture) ; le workflow de montée de version qui fait tourner les images publiées est dans [Montées de version](/fr/self-hosted/operate/upgrades). Si ton fork est non-trivial, la conversation qui vaut la peine d'être lancée avant que tu n'écrives du code est celle sur le Discord ou les GitHub Discussions du projet — beaucoup de forks finissent par être des fonctionnalités qui attendent d'atterrir en amont. # Architecture des conteneurs Source: https://tale.dev/docs/fr/self-hosted/operate/container-architecture Une instance Tale, ce sont huit conteneurs câblés par docker compose. La page d'architecture a couvert à quoi sert chaque conteneur ; cette page-ci est la version de l'opérateur — quel conteneur possède quel travail, comment un message chat y circule et à quoi ressemble le mode de défaillance quand l'un d'eux meurt. Lis ceci quand tu es d'astreinte. Reviens-y quand tu décides quel conteneur rouler en premier pendant une montée de version. ## Les huit conteneurs, avec leurs tâches | Conteneur | Tâche | Une panne affecte | | -------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `tale-proxy` | Terminaison TLS + routage en bordure | Tous les ingress — aucun client ne joint l'UI | | `tale-platform` | Serveur UI, livraison des assets statiques | Le navigateur voit 502 ; l'API reste joignable | | `tale-convex` | Actions/queries/mutations backend + WebSocket, plus RAG, crawling et génération de documents en in-process | L'UI charge mais sans données ; les chats en vol stagnent ; l'ingestion stagne | | `tale-db` | Postgres opérationnel pour Convex | Convex bascule en lecture seule ; les écritures bloquent | | `tale-knowledge-db` | Postgres du corpus de connaissances (fragments de documents, embeddings, pages crawlées) | La recherche de connaissances renvoie vide ; l'ingestion échoue | | `tale-sandbox-llm-gateway` | Gateway LLM pour les agents de code en sandbox | Les agents en sandbox ne joignent aucun modèle ; le chat n'est pas affecté | | `tale-sandbox-egress` | Sortie réseau pour code sandbox | L'outil **Exécuter du code** échoue avec « egress denied » ; le rendu web échoue | | `tale-sandbox` | Runtime sandbox + navigateur headless pour le rendu web et la génération de documents | **Exécuter du code**, le rendu de crawl web et la génération de documents échouent | Un conteneur est exposé au réseau public (`tale-proxy` pour HTTPS, et optionnellement `tale-sandbox-egress` sortant pour la sandbox) ; le reste est interne seulement. Le sidecar `tale-controller`, à activer explicitement (le profil `controller`), est éteint par défaut ; une fois activé, il redémarre `tale-convex` sur une requête signée pour qu'un changement de résidence des données s'applique sans donner à la plateforme l'accès à Docker. ## Le chemin de requête Un message chat fait un aller-retour par les conteneurs : 1. Navigateur → `tale-proxy` (TLS terminé). 2. `tale-proxy` → `tale-platform` pour HTML/JS, → `tale-convex` pour API + WebSocket. 3. `tale-convex` lit la config fournisseur de l'organisation, choisit le modèle, ouvre un flux vers le fournisseur amont. 4. Si l'agent récupère des connaissances : `tale-convex` exécute la recherche RAG en in-process, interrogeant directement `tale-knowledge-db` — sans service de récupération séparé sur le chemin. 5. Si l'agent exécute du code : `tale-convex` → `tale-sandbox` → `tale-sandbox-egress` pour tout appel sortant. 6. Le flux du fournisseur renvoie des tokens via `tale-convex` jusqu'au navigateur via le WebSocket. Le chemin chaud est court. Si la latence du chat semble fausse, le conteneur à blâmer est presque toujours le fournisseur amont, pas Tale ; les endpoints de métriques sur `tale-convex` (qui porte désormais aussi les timings RAG et de crawl) exposent le temps passé à chaque saut. ## Le plan sandbox L'exécution de code en sandbox tourne dans `tale-sandbox`, avec `tale-sandbox-egress` comme seule couture réseau. La séparation en deux conteneurs est délibérée : `tale-sandbox` lui-même n'a aucune sortie réseau ; chaque requête que le code sandbox fait passe par `tale-sandbox-egress`, qui bloque les métadonnées cloud et les plages privées au niveau IP et — quand l'opérateur définit `SANDBOX_EGRESS_ALLOWLIST` — impose en plus une allowlist d'hôtes en refus par défaut. Si le conteneur egress est down, le code sandbox qui a besoin du réseau échoue en mode fermé avec « egress denied » — pas un timeout silencieux. Le runtime sandbox embarque Chromium et Playwright, donc le backend convex le réutilise pour le travail headless qu'il ne peut pas faire en in-process : rendre une page JavaScript pendant un crawl web, et transformer du HTML généré en PDF ou en image. Ces tâches tournent comme des exécutions sandbox éphémères plutôt que du code utilisateur, mais elles empruntent la même couture d'egress et d'isolation. La sandbox est le seul conteneur qui exécute du code potentiellement non fiable (scripts de compétence fournis par l'utilisateur, invocations **Exécuter du code** d'agent) ; le reste de la stack exécute le code propre à la plateforme. ## Modes de défaillance — à quoi ressemble une panne de chaque conteneur **`tale-proxy` en panne.** Le handshake TLS échoue ; chaque client voit une erreur de connexion. Dans l'hôte, les conteneurs plateforme et convex restent debout — redémarre proxy en premier. **`tale-platform` en panne.** Le navigateur obtient 502 du proxy ; l'API continue de marcher. Les onglets navigateur existants avec assets en cache continuent à parler à convex via le WebSocket et peuvent ne pas s'en apercevoir avant un rechargement. **`tale-convex` en panne.** Le navigateur charge le shell UI mais rien ne se remplit. Les boucles de reconnexion WebSocket. Redémarrer convex est sûr — les sessions sont côté serveur ; les clients se réabonnent à la reconnexion. **`tale-db` en panne.** Convex entre dans son mode dégradé : lectures depuis le cache, écritures en file. De longues pannes finissent par afficher des toasts « échec de l'enregistrement ». **`tale-knowledge-db` en panne.** L'ingestion de documents échoue et la recherche de connaissances renvoie vide — les agents qui récupèrent des connaissances obtiennent un ensemble de résultats vide et un avertissement dans le log d'exécution. Le reste de l'app continue de marcher ; les chats sans connaissances ne sont pas affectés. Redémarrer le conteneur règle ça, et les téléversements en vol retentent à la passe suivante. **`tale-sandbox` / `tale-sandbox-egress` en panne.** Les appels de l'outil **Exécuter du code** retournent une erreur et les scripts de compétence échouent. Parce que le backend convex rend les pages web et génère les documents via le runtime sandbox, un crawl web qui a besoin de rendu JavaScript et la génération de documents échouent aussi en mode fermé tant que la sandbox est down. Les agents qui n'utilisent aucun de ces éléments continuent de marcher. **`tale-sandbox-llm-gateway` en panne.** Les agents de code en sandbox perdent leur chemin vers un fournisseur de modèles. Le chat ordinaire — qui appelle les fournisseurs directement depuis convex, pas via la gateway LLM — n'est pas affecté. ## Où cela s'inscrit Cette page est la carte de l'opérateur ; la [vue d'ensemble de l'architecture](/fr/self-hosted/overview) est l'introduction à la même image, la page [Dépannage](/fr/self-hosted/operate/observability/troubleshooting) est l'index par symptôme quand quelque chose a mal tourné. Si tu fixes des seuils d'alerte, [Opérations](/fr/self-hosted/operate/observability/operations) nomme les signaux à câbler. # Comment lire les notes de version Source: https://tale.dev/docs/fr/self-hosted/operate/release-notes/format Tale publie une version par minor et des patches comme tags correctifs entre elles. Les notes de version pour chaque tag suivent la même forme afin que tu puisses en scanner une en une minute et savoir si la montée de version est un bump de cinq minutes ou une fenêtre de maintenance. Cette page couvre le format : la promesse semver, ce que chaque section garantit, et où lire plus en profondeur quand une ligne pointe vers une migration. Les notes elles-mêmes vivent sur la page de release GitHub de chaque tag. La CLI les fait aussi remonter — `tale update --notes` imprime les notes de la version qu'elle est sur le point d'installer. ## La promesse semver Les versions Tale sont en semver, et le numéro de version est le fait principal d'une montée de version. - **Patch (`0.9.0 → 0.9.1`)** — corrections de bugs uniquement. Pas de migration de schéma, pas de changement de config, pas de changement de comportement autre que le fix lui-même. Sûr à monter sans lire au-delà de la section sécurité. - **Minor (`0.9.x → 0.10.x`)** — nouvelles fonctionnalités, possiblement des migrations forward-only. Rétrocompatible par défaut ; les obsolescences sont annoncées une minor à l'avance. - **Major (`0.x → 1.x`)** — les changements breaking sont permis. Porte toujours un lien vers les notes de migration en haut de la release ; lis-les de bout en bout avant de commencer. La ligne de version en haut de chaque page de release nomme le type de bump en clair pour que tu n'aies pas à faire l'arithmétique toi-même. ## Les sections que chaque release a Chaque page de release est la même liste ordonnée de sections. Les sections vides sont omises, pas laissées vierges — si tu ne vois pas une section, c'est qu'il n'y a rien à rapporter là. - **Highlights** — un ou deux paragraphes nommant à quoi sert la release. Lis ça en premier. - **Changements breaking** — chaque changement qui demande à l'opérateur de faire quelque chose avant ou après la montée de version. Chaque ligne nomme le symptôme que tu rencontrerais si tu sautais, et l'action qui l'évite. - **Obsolescences** — fonctionnalités qui marchent encore dans cette release mais marquées pour suppression. Chaque ligne nomme la version de suppression pour que tu planifies la bascule. - **Sécurité** — entrées au format CVE pour les fixes qui ferment une vulnérabilité. Le flux complet vit sous [Avis de sécurité](/fr/self-hosted/operate/security/advisories) ; les notes de version portent le résumé d'une ligne plus le lien vers l'avis. - **Fonctionnalités et corrections** — la longue liste. Groupée par domaine (Platform, CLI, Docs) ; chaque ligne se lit comme une phrase. - **Notes de migration** _(versions majeures et certaines mineures)_ — le parcours lié à travers les migrations de schéma, les changements de fichier de config ou les renommages côté opérateur. À lire systématiquement pour les majeures. ## Comment scanner une release Lis la ligne de version, les highlights et la section des changements breaking. Si la section breaking est vide et que la section sécurité ne nomme pas un fix qui touche ton install, la montée de version est la séquence `tale update` + `tale deploy` depuis [Montées de version](/fr/self-hosted/operate/upgrades). Si l'une ou l'autre des sections a des lignes, parcours-les avant de lancer `tale deploy`. ```text 0.12.0 (minor) — 14/05/2026 Highlights Les tool calls en streaming streament maintenant dans le chat à mesure qu'ils émettent. Changements breaking (aucun) Obsolescences AGENTS_LEGACY_PROMPT env var — retirée en 0.14. Sécurité CVE-2026-XXXX — bypass patché dans la sandbox run-code. Voir : avis TAL-2026-007. ``` La forme ci-dessus est ce qu'imprime `tale update --notes`. La version web de la même release ajoute des liens sur chaque ligne d'avis et de migration. ## Où cela s'inscrit Le format des notes de version est le contrat entre le projet et l'opérateur — la même forme à chaque release pour que la décision de montée de version soit un scan, pas une lecture profonde. Les prochaines étapes naturelles sont [Montées de version](/fr/self-hosted/operate/upgrades) pour la mécanique de déploiement et [Avis de sécurité](/fr/self-hosted/operate/security/advisories) pour le flux long format des vulnérabilités vers lequel la section sécurité pointe. # tale-daemon Source: https://tale.dev/docs/fr/self-hosted/operate/tale-daemon `tale-daemon` exécute les tâches du board Tale sur une machine que vous contrôlez, avec les CLIs d'agents de code que vous avez déjà : **Claude Code** (`claude`) et **Codex** (`codex`). Liez un agent à une runtime dans sa configuration : ses tâches affectées sont envoyées au daemon au lieu de la boucle de modèle interne de Tale ; le résultat revient en commentaire (avec statistique de diff) et la tâche se gare à _En revue_ comme tout travail d'agent. Pour des exécutions pilotées par le chat des mêmes CLIs dans un bac à sable géré, voir [Agents externes](/fr/platform/agents/external-agent). ## Installation ```sh tale daemon setup # URL de base, clé API, espace de travail, plafond de permission tale daemon start # enregistrement + boucle de réclamation (Ctrl-C draine l'exécution) tale daemon status # configuration, CLIs détectées, connectivité serveur ``` `setup` génère une identité stable et stocke la configuration dans `~/.tale-daemon/config.json` (mode 600). Utilisez une clé API Tale normale (**Paramètres → API → REST**) ; définissez `TALE_DAEMON_API_KEY` pour garder la clé hors du fichier. Les daemons connectés apparaissent sous **Paramètres → API → Runtimes** avec leur statut en direct. Le plus rapide est le bouton **Générer une clé et copier la commande** sous **Paramètres → API → Runtimes** : il génère une nouvelle clé API et copie une commande prête à l'emploi, avec l'URL de cet espace et la clé déjà renseignées. Toute réponse demandée par `setup` peut aussi être passée en option, de sorte que la commande s'exécute sans surveillance : ```sh tale daemon setup --yes --url https://your-org.tale.dev --key <api-key> tale daemon start ``` La clé figure dans la ligne de commande — traitez l'extrait comme un secret et révoquez la clé sous **Paramètres → API → REST** en cas de fuite. ## Confidentialité & permissions - Les **chemins locaux ne quittent jamais la machine** — seules les clés d'espace de travail que vous choisissez sont annoncées au serveur. - La permission effective d'une exécution est **min(configuration serveur, plafond du daemon)**. `full_auto` (saut des permissions / accès complet) exige donc un opt-in des _deux_ côtés. La valeur par défaut est `safe`. ## Comment les exécutions se déroulent - **Cadence** : le daemon interroge le serveur avec un backoff piloté par celui-ci (3 s après du travail, 15 s au repos, plafonné à 60 s après dix minutes d'inactivité — un daemon inactif coûte environ une requête par minute). Un battement de cœur de 15 s pendant une exécution renouvelle le bail et récupère les annulations (SIGTERM). - **Isolation** : chaque exécution se déroule dans son propre worktree git sur une branche `tale/run-…`. Rien n'est poussé ; la statistique de diff accompagne le rapport. - **Sessions** : les exécutions de révision (retours de revue) reprennent la session CLI précédente quand l'adaptateur le permet. ## Gestion des échecs | Situation | Comportement | | -------------------------------------------------- | --------------------------------------------------------------------------- | | Aucun daemon ne réclame l'exécution sous 2 minutes | Échec (`runtime_offline`), la tâche revient à _À faire_ avec un commentaire | | Le daemon meurt en cours d'exécution (bail perdu) | Une reprise depuis un worktree propre, puis échec | | L'exécution dépasse 30 minutes | Timeout dur, traitement comme ci-dessus | | La CLI sort avec un code d'erreur | Une reprise, puis échec avec extrait de l'erreur | Toutes les exécutions externes partagent l'enregistrement interne — budgets, plafonds de simultanéité et métriques s'appliquent à l'identique. # Backups et restauration Source: https://tale.dev/docs/fr/self-hosted/operate/backups-and-restore L'unité de backup de Tale est le snapshot de volume : un tar checksummé, pris à containers en pause, de chaque volume de données de l'instance, écrit dans un volume `backups` dédié qui vit à côté des données qu'il protège. La CLI en prend un automatiquement avant toute étape de déploiement qui peut migrer des données, et `tale backup` en prend un à la demande. La récupération, c'est `tale restore <snapshot-id>` plus un redéploiement de la version correspondante — cette paire est la réponse à une montée de version échouée, et la raison pour laquelle `tale rollback` peut se permettre de refuser tout ce qui dépasse un pas de patch. Le contexte d'architecture vit dans [Architecture des conteneurs](/fr/self-hosted/operate/container-architecture) ; cette page couvre ce qu'un snapshot contient, quand il est pris, comment la copie quitte l'hôte et le walk de restauration. ## Ce qu'un snapshot contient | Volume | Contient | | ---------------------------- | --------------------------------------------------------- | | `db-data` | Postgres — agents, runs, l'audit log | | `convex-data` | Config d'org, secrets de fournisseurs, branding téléversé | | `rag-data` | L'index vectoriel construit depuis tes documents | | `crawler-data` | Connaissance web crawlée | | `caddy-data`, `caddy-config` | Certificats TLS et état du proxy | Chaque snapshot est un répertoire nommé comme `20260611-142530-deploy` dans le volume `backups` du projet : un `.tar.gz` par volume, un sidecar `.sha256` chacun et un `manifest.json` écrit en dernier. Un répertoire sans manifest est un snapshot incomplet — il n'apparaît jamais dans les listings et ne peut jamais être restauré. Deux choses vivent hors des volumes et demandent une capture séparée : le workspace du projet (le répertoire qui contient `tale.json`) et `.env`. ## Quand les snapshots sont pris `tale deploy` snapshotte avant sa première étape mutante dès que le déploiement peut changer des données : la version cible diffère de celle qui tourne, ou un push de config hôte (`--override` / `--override-all`) est demandé. Pendant que chaque volume est mis en tar, les conteneurs qui l'utilisent sont mis en pause quelques secondes pour que l'archive soit cohérente après crash — une copie à chaud d'un répertoire Postgres en marche n'est pas restaurable. Un snapshot échoué interrompt le déploiement. `--skip-backup` outrepasse cela sur `tale deploy` — tes propres backups externes deviennent alors le seul chemin de récupération, et c'est exactement pour ça que le flag logge un avertissement bien visible. ```bash # Prendre un snapshot tout de suite tale backup ``` ## Rétention La rotation garde les cinq snapshots les plus récents et tout ce qui date des 14 derniers jours — selon ce qui est le plus généreux. Un snapshot n'est supprimé que s'il est à la fois au-delà de la fenêtre de compte et plus vieux que la fenêtre d'âge ; une instance calme garde donc ses derniers snapshots indéfiniment. Ajuste les fenêtres avec `BACKUP_KEEP_COUNT` et `BACKUP_KEEP_DAYS` dans `.env`. ## Copie hors-hôte Les snapshots vivent sur le même hôte que les données qu'ils protègent — un disque mort emporte les deux. Pointe ton outillage de backup existant (Restic, Borg, Velero, snapshots de cloud provider) sur le volume `backups`, et capture le workspace du projet et `.env` dans le même job. Tale n'embarque pas d'étape d'upload — garder la copie hors-hôte sous ton contrat de backup existant est délibéré. ```bash # crontab sur l'hôte — copie Restic horaire du volume backups vers S3 0 * * * * restic -r s3:s3.amazonaws.com/bucket/tale backup \ /var/lib/docker/volumes/<project-id>_backups/_data ``` Trouve le chemin hôte du volume avec `docker volume inspect <project-id>_backups` ; l'id du projet vit dans `tale.json`. ## Restaurer un snapshot `tale restore` sans argument liste ce qui est disponible ; avec un id, il vérifie les checksums, vide les volumes de données et extrait le snapshot. Il refuse tant qu'un conteneur du projet tourne — passe `--stop` pour les arrêter — et demande confirmation avant de toucher à quoi que ce soit. ```bash # Voir ce qui est disponible tale restore # Arrêter le stack et restaurer tale restore 20260611-142530-deploy --stop # Remonter le stack sur la version qui correspond aux données tale update --version 0.9.6 tale deploy --stop ``` Le redéploiement de la version correspondante fait partie de la restauration, ce n'est pas un extra optionnel : le snapshot a capturé les données exactement comme cette version de la plateforme les a laissées, et un binaire plus récent relancerait immédiatement ses migrations dessus. La sortie de la restauration imprime la version exacte enregistrée dans le manifest du snapshot. ## Drill de restauration Fais tourner le drill trimestriellement sur un hôte non-production. Le drill n'est pas « un snapshot existe-t-il » — c'est « un hôte frais peut-il être reconstruit depuis la copie hors-hôte du volume `backups`, le workspace du projet et `.env` en moins d'une heure ». Les modes d'échec que le drill attrape : un job hors-hôte qui n'a jamais capturé le workspace, et un `.env` périmé qui ne correspond plus aux exigences du binaire courant. ## Où cela s'inscrit Les snapshots sont la partie bon marché ; le drill de restauration est ce qui prouve qu'ils marchent, et la règle redéployer-la-version-correspondante est la seule chose à retenir — la récupération n'est jamais « faire reculer le binaire », c'est « restaurer les données et déployer la version à laquelle elles appartiennent ». Le flow de montée de version que ces snapshots protègent vit dans [Montées de version](/fr/self-hosted/operate/upgrades) ; la checklist de durcissement qui nomme les backups comme une ligne est dans [Durcissement](/fr/self-hosted/operate/security/hardening). # Avis de sécurité Source: https://tale.dev/docs/fr/self-hosted/operate/security/advisories Tale publie un avis de sécurité pour chaque vulnérabilité qui se ferme par une release patchée. Le flux vit sous GitHub Security Advisories sur le dépôt `tale-project/tale` et se miroite vers un endpoint RSS que les opérateurs peuvent brancher dans leur alerting. Cette page couvre le format que suit chaque avis, l'échelle de sévérité que Tale utilise, le calendrier de divulgation auquel les mainteneurs s'engagent, et les trois chemins d'abonnement. Les avis sont l'enregistrement long format. Le résumé d'une ligne plus un lien apparaît dans la section **Sécurité** de chaque [note de version](/fr/self-hosted/operate/release-notes/format). ## Le format des avis Chaque avis est un GitHub Security Advisory avec un identifiant stable de la forme `TAL-YYYY-NNN` (ID interne de Tale) plus le `CVE-YYYY-NNNNN` upstream s'il en a un d'attribué. Le corps est le même ensemble ordonné de sections pour qu'un opérateur scanne les faits porteurs sans lire la prose. - **Résumé** — une phrase nommant ce qu'un attaquant pourrait faire et ce que le fix change. - **Versions affectées** — la plage de versions qui contient la vulnérabilité, en forme semver (`>=0.8.0, <0.12.3`). - **Versions patchées** — la première release qui contient le fix. Monter à ou au-delà de cette version ferme la vulnérabilité. - **Sévérité** — un des quatre niveaux ci-dessous, plus le vecteur CVSS 3.1 pour les opérateurs qui scorent contre leur propre threat model. - **Contournements** — quoi régler, désactiver ou bloquer pour mitiger la vulnérabilité quand une montée de version immédiate n'est pas possible. Vide quand aucun contournement n'existe. - **Crédits** — le rapporteur, quand il a demandé à être nommé. La ligne des versions patchées est celle sur laquelle la plupart des opérateurs atterrissent en premier ; la montée de version elle-même est la séquence à deux commandes de [Montées de version](/fr/self-hosted/operate/upgrades). ## L'échelle de sévérité Tale utilise quatre niveaux. Le niveau est posé à partir du score CVSS et de l'accessibilité de la surface vulnérable sur un install par défaut. | Niveau | CVSS | Ce que ça veut dire | | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Critical | 9.0+ | Exécution de code à distance pré-authentifiée ou exfiltration de données non authentifiée. Patche sous 24 heures. | | High | 7.0–8.9 | Escalade authentifiée, évasion de sandbox ou fuite de données cross-tenant. Patche sous une semaine. | | Moderate | 4.0–6.9 | Divulgation d'information, déni de service ou escalade demandant des préconditions rares. Patche à la prochaine fenêtre de maintenance. | | Low | 0.1–3.9 | Fixes de défense en profondeur et durcissement sans chemin d'exploitation connu. Patche quand ça t'arrange. | Le vecteur CVSS te laisse re-scorer contre ton propre déploiement — un avis noté High contre un install public peut être Low contre un air-gappé. ## Le calendrier de divulgation Les mainteneurs s'engagent sur le calendrier suivant à partir du moment où un rapport atterrit à `security@tale.dev` : - **Sous 72 heures** — accusé de réception, un triage call et un identifiant TAL attribué. - **Sous 14 jours** — un fix ou un contournement publié en privé au rapporteur, et la version patchée planifiée. - **À la sortie du fix** — l'avis est publié sur GitHub, l'attribution du CVE est demandée, et la section sécurité des notes de version porte le résumé. - **30 jours après la sortie** — le détail technique dans l'avis s'étend avec le reproducteur (quand reproduire en public ne met plus en risque les installs non patchés). Les rapporteurs peuvent demander un délai s'ils ont besoin de plus de temps pour divulguer ; les mainteneurs acceptent jusqu'à 90 jours avant de publier le résumé malgré tout. Côté ingénierie, les correctifs de dépendances passent par une voie rapide pour que la version corrigée arrive vite : Renovate ouvre une PR de mise à jour de sécurité dans les 24 heures suivant un advisory amont — en contournant le délai d'âge de version appliqué aux mises à jour de routine — et la CI bloque tout merge introduisant un advisory connu noté High ou Critical. Un CVE de dépendance divulgué devient ainsi une version Tale corrigée en quelques jours, et non au prochain cycle de routine. ## S'abonner Trois chemins vers le même flux : ```text Watch GitHub — github.com/tale-project/tale → Watch → Custom → Security alerts RSS — https://github.com/tale-project/tale/security/advisories.atom Digest courriel — security-announce@tale.dev (un courriel par avis, pas de trafic entre) ``` Le flux RSS est ce que la plupart des opérateurs branchent dans Slack ou PagerDuty ; le digest courriel est pour les équipes d'une personne qui ne font pas tourner de pipeline d'alerting. ## Où cela s'inscrit Le flux des avis est un des deux contrats qui rendent Tale auto-hébergeable sereinement — les notes de version nomment ce qui change, les avis nomment ce qui n'allait pas. Les prochaines lectures naturelles sont [Comment lire les notes de version](/fr/self-hosted/operate/release-notes/format) pour le format de changelog correspondant et [Durcissement](/fr/self-hosted/operate/security/hardening) pour la checklist qui limite l'exposition avant qu'un avis ne tire. # Cryptographie Source: https://tale.dev/docs/fr/self-hosted/operate/security/cryptography Cette page est l'inventaire de chaque primitive cryptographique sur laquelle Tale s'appuie : ce qui protège les secrets sur le disque, ce qui protège le trafic sur le réseau, comment les mots de passe sont hachés, et comment le journal d'audit prouve qu'il n'a pas été altéré. Elle est écrite pour les opérateurs et les auditeurs de conformité qui doivent répondre à « quels algorithmes, quelles longueurs de clé, où sont les clés » face à une norme comme BSI TR-02102-1 — Tale utilise déjà des primitives conformes, et cette page est l'endroit où elles sont consignées. Les affirmations ici sont vérifiées contre le code source ; là où une primitive est configurable, la variable d'environnement qui la contrôle est nommée pour que tu puisses auditer ton propre déploiement. Ce n'est pas un substitut au chiffrement du disque hôte — vois [Durcissement](/fr/self-hosted/operate/security/hardening) pour la couche sous l'application. ## Données au repos Tale chiffre deux classes de secrets au repos, avec deux mécanismes différents. **Les clés API des fournisseurs** vivent dans `providers/*.secrets.json` et sont chiffrées avec [SOPS](/fr/self-hosted/configuration/secrets-with-sops) en utilisant une clé **age**. SOPS chiffre chaque valeur avec **AES-256-GCM** et enveloppe la clé de données vers le destinataire age, dont l'échange de clés est **X25519**. Une valeur chiffrée se lit `ENC[AES256_GCM,data:…,iv:…,tag:…]` sur le disque ; le déchiffrement se fait in-process et la clé privée age ne quitte jamais la mémoire du conteneur platform. **Les champs chiffrés par l'application** — tokens d'intégration OAuth et identifiants similaires stockés en base — sont chiffrés avec **AES-256-GCM** via un JWE compact (`alg: dir`, `enc: A256GCM`). La clé de 32 octets vient de `ENCRYPTION_SECRET` (base64) ou `ENCRYPTION_SECRET_HEX` (hex) ; la plateforme refuse de démarrer le chemin de chiffrement avec une clé qui ne fait pas exactement 32 octets. Le magasin de données Convex et les volumes Postgres sont protégés par l'hôte : fais-les tourner sur un système de fichiers chiffré (LUKS, ou le chiffrement de volume de ton fournisseur cloud). Tale ne stocke pas d'identifiants en clair — une clé de fournisseur ou un token OAuth est soit chiffré par SOPS sur le disque, soit chiffré en AES-256-GCM en base, jamais écrit en clair. **Les données personnelles des clients et les enregistrements applicatifs** — noms, adresses e-mail et postales, contenu des conversations — sont protégés au repos par les mêmes couches qui protègent la base dans son ensemble : le chiffrement au repos de Convex, TLS 1.3 en transit, et la sécurité au niveau des lignes (RLS) qui restreint chaque lecture à l'organisation de l'appelant. Le chiffrement applicatif au niveau des champs est conçu pour les secrets — clés de fournisseur et tokens OAuth, écrits une fois et lus par un unique chemin de code. Les données personnelles sont différentes : elles sont filtrées, triées et recherchées par valeur exacte, et la table des clients est indexée par organisation et e-mail. Chiffrer ces colonnes au niveau des champs casserait les recherches par égalité et l'indexation — sauf à les coupler à un schéma de hachage recherchable qui révèle l'égalité même qu'il est censé masquer — au prix d'une rotation des clés et sans protection que le système de fichiers hôte chiffré sous l'application n'offre déjà contre un volume volé. Si ta réglementation de conformité exige en plus un chiffrement des données personnelles au niveau des champs, c'est une modification applicative délibérée plutôt qu'un défaut livré par Tale. ## Données en transit Tout le trafic navigateur et API termine TLS au reverse proxy (Caddy), qui négocie TLS 1.3 (avec TLS 1.2 comme plancher) et obtient les certificats automatiquement. Les suites de chiffrement sont les défauts modernes du proxy — AES-256-GCM et ChaCha20-Poly1305 avec échange de clés ECDHE. Configure le domaine et la source de certificat dans [TLS et domaines](/fr/self-hosted/configuration/tls-and-domains) ; le trafic entre conteneurs reste sur le réseau Docker interne de l'hôte. ## Hachage des mots de passe Les comptes à mot de passe local sont hachés avec **bcrypt** (via Better Auth), de sorte qu'une ligne de base de données volée ne révèle pas le mot de passe et qu'une vérification coûte délibérément ~100 ms — ce qui explique aussi pourquoi le timing du chemin de connexion est brouillé (vois [Authentification](/fr/self-hosted/configuration/authentication)). Les sessions sont signées avec `BETTER_AUTH_SECRET` (HMAC) ; faire tourner ce secret invalide toute session existante. ## Intégrité du journal d'audit Le journal d'audit est inviolable grâce à une **chaîne de hachage SHA-256** : chaque entrée stocke `SHA-256(previousHash + enregistrement canonisé)`, donc modifier ou supprimer une entrée historique casse la chaîne à cet endroit et à chaque entrée suivante. Les entrées portent en plus une signature **HMAC-SHA-256**. La vérification d'intégrité admin vérifie les deux ; vois [Journaux d'audit](/fr/platform/admin/governance/audit-logs). ## Correspondance avec BSI TR-02102-1 Chaque primitive ci-dessous est dans l'ensemble recommandé de BSI TR-02102-1. Tale ne livre aucun algorithme déprécié (pas de MD5, SHA-1, DES ni RSA < 3072 sur une clé qu'il génère). | Usage | Algorithme | Taille de clé / sortie | Contrôlé par | | ----------------------------- | --------------------------------- | ---------------------- | --------------------------------------------- | | Secrets fournisseurs (disque) | AES-256-GCM + age (X25519) | 256 bits | `SOPS_AGE_KEY` / `SOPS_AGE_KEY_FILE` | | Champs app (base de données) | AES-256-GCM (JWE `dir`/`A256GCM`) | 256 bits | `ENCRYPTION_SECRET` / `ENCRYPTION_SECRET_HEX` | | Transport | TLS 1.3 (AES-256-GCM, ECDHE) | 256 bits | Reverse proxy / `tls-and-domains` | | Hachage des mots de passe | bcrypt | sel par hachage | Better Auth (intégré) | | Signature de session | HMAC-SHA-256 | 256 bits | `BETTER_AUTH_SECRET` | | Intégrité d'audit | chaîne SHA-256 + HMAC-SHA-256 | 256 bits | intégré | ## Stockage et rotation des clés Trois secrets sont porteurs, et chacun a un chemin de rotation. La **clé privée age** (`SOPS_AGE_KEY`) déchiffre les secrets fournisseurs ; fais-la tourner en ajoutant un nouveau destinataire et en re-chiffrant, en suivant le parcours dans [Secrets avec SOPS](/fr/self-hosted/configuration/secrets-with-sops). La **clé de chiffrement de champ** (`ENCRYPTION_SECRET`) déchiffre les identifiants en base ; la faire tourner exige de re-chiffrer les lignes concernées, planifie-la donc comme une étape de maintenance plutôt qu'un échange à chaud. Le **secret d'auth** (`BETTER_AUTH_SECRET`) signe les sessions ; le faire tourner déconnecte tout le monde à la requête suivante. Les trois ne vivent que dans l'environnement du conteneur platform — ne les committe jamais et range-les dans ton gestionnaire de secrets de référence. ## Où cela s'inscrit La cryptographie dans Tale est en couches : SOPS+age et AES-256-GCM protègent les secrets au repos, TLS 1.3 les protège en transit, bcrypt protège les mots de passe, et une chaîne SHA-256 prouve que le journal d'audit est intact — toutes des primitives qui sont dans l'ensemble recommandé de BSI TR-02102-1, avec les variables d'environnement de contrôle ci-dessus pour que tu puisses vérifier ta propre instance. La couche sous l'application est l'hôte lui-même : [Durcissement](/fr/self-hosted/operate/security/hardening) couvre l'allowlist d'egress, l'isolation des conteneurs et les attentes de chiffrement de disque que cette page présuppose, et [Secrets avec SOPS](/fr/self-hosted/configuration/secrets-with-sops) est le guide opérationnel pour la clé age dont ces algorithmes dépendent. # Alertes d’intégrité du journal d’audit Source: https://tale.dev/docs/fr/self-hosted/operate/security/audit-log-integrity Tale vérifie la chaîne de hachage du journal d’audit de chaque organisation selon un planning et lève une alerte à l’instant où une vérification échoue. Cette page est le runbook de l’opérateur ou de l’admin qui a reçu cette alerte : comment lire le constat, comment séparer un vrai signal de falsification d’un artefact ordinaire de rétention ou de configuration, et quoi préserver avant de toucher à quoi que ce soit. L’alerte est volontairement bruyante parce qu’une vraie rupture est rare et grave — mais la plupart des ruptures qui se déclenchent en pratique ont une explication banale, donc le travail consiste à les écarter méthodiquement plutôt qu’à paniquer. ## Ce qui la déclenche Un cron quotidien parcourt la chaîne d’audit en append-only de chaque organisation, avec ses points de contrôle de rétention et de scrub. Quand une chaîne ne se vérifie pas, l’exécution fait deux choses. Elle écrit une ligne d’audit in-band de catégorie `security` — à chaque exécution en échec, pour que l’enregistrement durable soit toujours complet — et elle lève une notification out-of-band vers les admins de l’organisation, dans la cloche de notifications et dans ton canal Slack quand il y en a un de connecté. L’alerte out-of-band est dédupliquée. Tu reçois une notification à la première détection d’une rupture, et une autre seulement si elle change — une autre ligne rompue, ou un autre point de contrôle en échec — pas une nouvelle alarme chaque jour pour la même rupture. Une exécution propre ultérieure efface l’alerte d’elle-même ; une rupture différente, plus tard, en lève une nouvelle. ## Falsification ou lacune de configuration L’alerte arrive sous deux formes, et le titre te dit laquelle. **Échec du contrôle d'intégrité du journal d'audit** est la critique : la chaîne de hachage elle-même ne se vérifie pas, ou la signature d’un point de contrôle signé ne correspond pas à la clé configurée. Traite-la comme un signal de falsification possible tant que tu ne l’as pas expliquée. **Les signatures du journal d'audit ne peuvent pas être vérifiées** est un avertissement calme, pas une intrusion : un point de contrôle est signé, mais le déploiement n’a aucune `TALE_AUDIT_SIGNING_KEY` configurée pour vérifier cette signature. Rien n’a été forgé — Tale ne peut pas prouver que le point de contrôle est authentique tant que tu n’as pas restauré la clé. Le panneau dans le produit reflète la distinction : une chaîne saine montre le badge vert **Vérifié**, un incident actif le badge rouge **Alerte d'intégrité active**, et une organisation que le cron n’a pas encore atteinte montre **Pas encore vérifié**. ## Ouvrir le panneau d’intégrité Les admins d’une organisation inspectent la chaîne depuis **Paramètres > Gouvernance > Journaux d'audit**. Le panneau **Intégrité de la chaîne** en haut de la page montre le badge de statut, l’heure du dernier contrôle automatique et un bouton **Vérifier maintenant** qui relance la même vérification à la demande. Si tu arrives depuis la notification, cliquer sur l’alerte te mène directement à la ligne signalée dans le tableau d’audit au lieu du haut du journal. Lance **Vérifier maintenant** pour voir le constat structuré. Pour une rupture de la chaîne de hachage, le panneau montre **Intégrité de la chaîne rompue** avec l’**ID de l'entrée** de la première ligne en échec, le moment (**Survenue le**), le **Hachage attendu** et le **Hachage stocké** qui n’a pas correspondu — plus un bouton **Ouvrir cette entrée** qui révèle la ligne dans le tableau. Pour un problème de point de contrôle, il montre **Échec de la vérification du point de contrôle** avec l’**ID du point de contrôle** et une **Raison**. Note ces détails avant de changer quoi que ce soit : ils sont la preuve. ## Écarter les causes bénignes Une rupture de hachage n’est un signal de falsification que si rien de légitime ne l’explique, et le vérificateur connaît déjà les trois événements ordinaires derrière presque toutes les alertes — les confirmer est ton premier geste. **Une coupe de rétention.** Quand la rétention supprime définitivement d’anciennes lignes, la tête de chaîne survivante pointe vers une ligne qui n’existe plus. Le vérificateur ré-ancre la chaîne par-dessus la coupe grâce à un point de contrôle de rétention signé — une coupe propre se vérifie donc normalement. Si tu vois à la place **Les signatures du journal d'audit ne peuvent pas être vérifiées**, la coupe elle-même va bien — il manque au déploiement la `TALE_AUDIT_SIGNING_KEY` qui authentifie le point de contrôle. C’est une lacune de configuration, pas une falsification. **Un scrub RGPD.** Effacer une personne concernée vide ses champs sur place, ce qui changerait les hachages de ces lignes — un scrub écrit donc un point de contrôle de scrub signé couvrant les lignes touchées, et le vérificateur leur fait confiance sur cette base. Un scrub ne devrait jamais apparaître comme une rupture sur un déploiement qui a une clé de signature. **Les anciennes lignes d’avant la chaîne.** Les lignes écrites avant l’existence du chaînage de hachage d’audit ne portent aucun hachage d’intégrité. Le vérificateur les saute automatiquement ; ce n’est pas une rupture. Un vrai signal de falsification est un écart de hachage sans aucune de ces explications : pas de coupe de rétention à cet endroit, pas de scrub couvrant la ligne, et la clé de signature présente et correcte. ## Réagir à une vraie rupture Si le constat survit à ce triage — un écart de hachage que tu ne peux pas expliquer —, traite-le comme un incident de sécurité et préserve d’abord les preuves. Les lignes d’audit sont en append-only par conception ; ne supprime ni ne modifie aucune ligne, y compris la ligne signalée, car cela détruit l’enregistrement dont une enquête dépend. 1. Note le constat mot pour mot — l’**ID de l'entrée**, l’heure sous **Survenue le**, le **Hachage attendu** et le **Hachage stocké** (ou l’**ID du point de contrôle** et la **Raison**) affichés dans le panneau. Copie-les ou fais-en une capture plutôt que de te fier à la seule alerte. 2. Confirme si la clé de signature est configurée sur l’hôte, pour distinguer un vrai écart d’un point de contrôle invérifiable. Ceci rapporte la présence sans imprimer le secret : ```bash grep -q '^TALE_AUDIT_SIGNING_KEY=' .env && echo configured || echo missing ``` 3. Corrèle l’horodatage de la rupture avec l’activité récente — une passe de rétention, un scrub de personne concernée, un déploiement, une restauration de base de données ou un accès direct à la base. Une rupture alignée sur une action de maintenance a le plus souvent une cause ordinaire que tu peux maintenant nommer. 4. Si rien ne l’explique, escalade via ta politique d’incident de sécurité et traite la base de données comme potentiellement compromise jusqu’à preuve du contraire. Garde un snapshot de sauvegarde d’avant et d’après la rupture détectée pour l’investigation. ## Effacer l’alerte L’alerte est liée à l’incident, pas récurrente. Une fois la rupture résolue ou expliquée — la clé restaurée, l’artefact de rétention compris, une base falsifiée reconstruite depuis une sauvegarde saine —, la prochaine exécution quotidienne se vérifie proprement et efface l’alerte d’elle-même, et le badge **Intégrité de la chaîne** revient à **Vérifié**. Il n’y a aucune étape d’accusé de réception ou de rejet à retenir. Si une rupture différente apparaît plus tard, le contrôle lève une nouvelle alerte pour celle-là — couper le son n’est donc jamais nécessaire. ## Où cela s’inscrit Une alerte d’intégrité est une invitation à enquêter, pas un verdict — le contrôle quotidien tourne fort pour qu’une rare vraie rupture ne puisse pas se cacher parmi les journaux, et ce runbook est la façon de séparer ce cas rare des artefacts de rétention et de scrub derrière la plupart des alertes. Le mécanisme que le vérificateur contrôle — la chaîne de hachage SHA-256 et les points de contrôle signés en HMAC — est documenté dans [Cryptographie](/fr/self-hosted/operate/security/cryptography), et les coupes de rétention qui la ré-ancrent légitimement sont dans [Rétention](/fr/self-hosted/configuration/retention). Le panneau, les colonnes et l’export avec lesquels tu lis une ligne signalée vivent dans la référence [Journaux d'audit](/fr/platform/admin/governance/audit-logs) ; la checklist [Durcissement](/fr/self-hosted/operate/security/hardening) est l’endroit où ce monitoring s’allume en premier lieu. # Durcissement Source: https://tale.dev/docs/fr/self-hosted/operate/security/hardening Les défauts livrés par Tale sont sûrs pour le développement et raisonnables pour une petite installation en production. Passer de « raisonnable » à « prêt pour le régulateur » est une checklist, pas un flag de configuration — chaque ligne ci-dessous resserre une surface d'attaque spécifique. Walk la liste une fois avant d'ouvrir l'URL à de vrais utilisateurs, et walk-la à nouveau après chaque montée de version majeure. Le détail de référence pour chaque ligne vit ailleurs — TLS dans [TLS et domaines](/fr/self-hosted/configuration/tls-and-domains), backups dans [Backups et restauration](/fr/self-hosted/operate/backups-and-restore), rétention dans [Rétention](/fr/self-hosted/configuration/retention). Cette page est l'index qui nomme ce qu'il faut durcir et pointe vers la page qui le walk. ## Hôte | Élément | Pourquoi ça compte | | ---------------------------------------- | ------------------------------------------------------------------ | | Utilisateur opérateur non-root | Limite le blast radius si l'utilisateur plateforme est compromis | | Auth SSH par clé uniquement | L'auth par mot de passe est la porte ouverte que les bots scannent | | Mises à jour de sécurité non surveillées | Patche l'OS sans attendre une fenêtre de maintenance | | Firewall hôte (ufw / nftables) | Ferme tout ce qui n'est pas 22, 80, 443 | | Chiffrement du disque au repos | Requis si tu fais tourner SOPS en mode clair | L'utilisateur non-root est celui que la plupart des équipes sautent. Les conteneurs de Tale font tourner leurs propres processus non-root à l'intérieur, mais le démon Docker lui-même tourne en root — opérer ce démon en tant qu'utilisateur opérateur (membre du groupe `docker`, pas en tant que root) est le resserrement le moins cher de cette page. Le walk complet vit dans [Installation serveur Linux de production](/fr/self-hosted/install/linux-server). ## Réseau Le proxy est la seule surface entrante. Bloque tout le reste. ```bash sudo ufw default deny incoming sudo ufw default allow outgoing sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable ``` Si tu fais tourner l'auth trusted-headers, le port plateforme ne doit pas être joignable directement depuis ailleurs que le proxy amont — tout ce qui peut le frapper avec les bons en-têtes devient cet utilisateur. Un réseau Docker ou une règle firewall hôte marchent tous les deux ; choisis-en un et vérifie-le depuis l'extérieur de l'hôte. ## TLS `TLS_MODE=selfsigned` est pour le développement. La production fait tourner `letsencrypt` (ou `external` si tu mets ton propre proxy TLS-terminant devant Tale). Le cron de renouvellement est automatique ; l'alerte qui sonne quand le renouvellement échoue est ce qui te sauve 90 jours plus tard. Voir [TLS et domaines](/fr/self-hosted/configuration/tls-and-domains). ## Secrets Chaque secret dans `.env` est sensible — le secret de signature d'auth, la clé de chiffrement, le mot de passe de base, la clé age, le bearer token de métriques. La barre minimale : - `.env` est en mode 0600 et appartient à l'utilisateur opérateur. - `BETTER_AUTH_SECRET`, `ENCRYPTION_SECRET_HEX`, `INSTANCE_SECRET` sont rotés depuis les valeurs d'exemple livrées dans `.env.example`. - `DB_PASSWORD` est changé du placeholder par défaut. - `SOPS_AGE_KEY` ou `SOPS_AGE_KEY_FILE` est défini — laisser les deux non définis est supporté mais réservé aux hôtes à disque chiffré avec gestion de secrets externe. Le walk SOPS complet et la procédure de rotation vivent dans [Secrets avec SOPS](/fr/self-hosted/configuration/secrets-with-sops). ## Audit logs Les audit logs sont immuables et bornés par rétention. Les frameworks de compliance attendent au moins un an ; la borne est imposée par déploiement, donc le réglage de l'org le plus strict est ce qui tourne effectivement. Fixe le plancher dans ta config opérateur pour correspondre au framework le plus lâche que tu supportes, et assure-toi que les backups capturent les lignes d'audit log avec le reste de la base. La référence de rétention vit dans [Rétention](/fr/self-hosted/configuration/retention). ## Backups Un backup qui n'a pas été restauré est un espoir, pas un backup. Le minimum : dumps Postgres quotidiens écrits par le cron `tale-db`, copiés hors-hôte dans l'heure, et un drill de restauration trimestriel qui reconstruit une instance fonctionnelle depuis le snapshot. La procédure complète est dans [Backups et restauration](/fr/self-hosted/operate/backups-and-restore). ## Isolation de la sandbox Run-code est la surface la plus risquée du produit — le seul endroit où un input fourni par l'utilisateur devient du code exécuté. `tale-sandbox` tourne sans cap privilégié, son réseau est interne uniquement, et `tale-sandbox-egress` est son seul chemin sortant. Au niveau des hôtes, ce chemin est ouvert par défaut : le code en sandbox atteint n'importe quel hôte public en HTTPS, tandis que les endpoints de métadonnées cloud et les plages d'adresses privées sont toujours bloqués au niveau IP — ce plancher tient dans toutes les configurations. Le levier de durcissement est `SANDBOX_EGRESS_ALLOWLIST`. Mets-la dans `.env` sur une liste de regex d'hôtes séparées par des pipes et recrée `tale-sandbox-egress` : le proxy bascule en refus par défaut — seuls les hôtes correspondants sont joignables. Un verrouillage limité aux registres, qui garde pip, npm, uv et Git via HTTPS fonctionnels : ```bash SANDBOX_EGRESS_ALLOWLIST=^pypi\.org$|^files\.pythonhosted\.org$|^registry\.npmjs\.org$|^objects\.githubusercontent\.com$|^codeload\.github\.com$|^github\.com$|^api\.github\.com$ ``` Garde la liste courte et préfère des hôtes spécifiques aux wildcards. Les installations de paquets sont régies séparément, via l'écran [politique run-code](/fr/platform/admin/governance/run-code-policy). ## Monitoring `METRICS_BEARER_TOKEN` est non défini dans `.env.example` — c'est intentionnel, pour qu'une installation fraîche ne leak pas de métriques. Règle le token, scrape depuis ton Prometheus, et les seuils d'alerte dans [Opérations](/fr/self-hosted/operate/observability/operations) couvrent les signaux client-impactants. La chaîne de hachage du journal d'audit est vérifiée automatiquement chaque nuit. Toute rupture déclenche une alerte de sécurité critique vers les admins de l'org — dans la cloche de notifications et, lorsque Slack est connecté, dans ton canal Slack — pour que toute altération ressorte même quand personne ne surveille les logs. Tu peux re-walk la même vérification à la demande depuis la page d'administration du journal d'audit. ## Où cela s'inscrit Le durcissement n'est pas une tâche d'une seule passe — la liste ci-dessus est ce que tu walks avant le lancement, et que tu re-walks après chaque montée de version ou après chaque changement de la forme du réseau. La prochaine chose qui vaut la lecture après ceci est la ligne ci-dessus que tu n'as pas encore faite. # Opérations Source: https://tale.dev/docs/fr/self-hosted/operate/observability/operations La page opérations est le playbook d'alerte — quels signaux valent la peine de réveiller quelqu'un, lesquels peuvent attendre un café, et à quoi ressemblent les cinq premières minutes d'un incident. La surface de métriques de Tale vit derrière `METRICS_BEARER_TOKEN` ; cette page suppose que tu as câblé Prometheus et Grafana selon [Configuration de l'observabilité](/fr/self-hosted/configuration/observability-config) et qu'il te faut maintenant savoir quels chiffres regarder. L'index par symptôme est dans [Dépannage](/fr/self-hosted/operate/observability/troubleshooting). Cette page est le côté proactif — signaux d'abord, checklist d'astreinte ensuite. ## Signaux qui méritent une alerte | Signal | Sévérité | Pourquoi ça compte | | ---------------------------------------------- | -------- | --------------------------------------------------------------- | | Sonde de santé `tale-proxy` en échec > 1 min | page | Chaque utilisateur voit une erreur de connexion | | Taux HTTP 5xx `tale-platform` > 5 % | page | L'UI est cassée pour une part significative des requêtes | | Tempête de reconnexion WebSocket `tale-convex` | page | L'UI charge mais aucune donnée ne circule | | Connexions Postgres > 80 % du pool | warn | Le prochain pic va commencer à bloquer | | Volume `db-data` > 80 % plein | warn | Le Postgres opérationnel passe en lecture seule à plein | | Volume `knowledge-db-data` > 80 % plein | warn | L'ingestion échoue quand la base du corpus est pleine | | `tale-knowledge-db` injoignable depuis convex | warn | La recherche de connaissances renvoie vide ; l'ingestion stagne | | Taux d'erreur de requête fournisseur > 20 % | warn | Le fournisseur LLM amont passe une mauvaise journée | | Backup quotidien non écrit | page | Le drill de restauration échouera au pire moment | | Renouvellement de cert TLS échoué | warn | Renouvelle 30 j avant l'expiration — tu as le temps | Les deux premières pages sont les seules réellement client-impactantes. Les warns attrapent les tendances avant qu'elles ne basculent dans le territoire page. ## Signaux de logs à grepper Les logs arrivent par stdout par conteneur, capturés par le driver `json-file` de Docker. Les quatre phrases qui signifient consistamment un souci : - `panic` ou `unexpected error` dans les logs `tale-convex` — crash d'action Convex. - `decryption failed` dans les logs `tale-platform` — mismatch entre clé age SOPS et fichier sur disque. - `429 Too Many Requests` répété d'un fournisseur — rate limit atteint, les agents vont commencer à échouer. - `connection refused` ou `ECONNREFUSED` vers `knowledge-db` dans les logs `tale-convex` — le backend ne peut pas joindre la base du corpus ; l'ingestion et la recherche de connaissances échouent. Pipe ceux-ci vers ton aggregator comme alertes dérivées ; les endpoints de métriques ne les exposent pas comme gauges. ## Checklist d'astreinte Quand une page atterrit, les cinq premières minutes suivent la même forme à chaque fois. 1. **Confirme que l'alerte est réelle.** Ouvre `$SITE_URL` dans un navigateur. Si l'UI charge et que le chat marche, tu regardes un souci de métriques ou de scraper, pas un client-impactant. 2. **Identifie le conteneur.** `docker compose ps` montre lequel est unhealthy ; `docker compose logs --tail=200 <service>` montre la dernière erreur. 3. **Redémarre le coupable le plus probable.** `docker compose restart <service>` résout une fraction surprenante des incidents — crashs de processus, watchers de fichiers périmés, pools de connexion épuisés. L'architecture est construite pour survivre proprement à un redémarrage de conteneur unique. 4. **Vérifie les fournisseurs amont.** `https://status.openai.com`, `https://status.anthropic.com`, etc. Si le fournisseur brûle, les agents échouent ; Tale n'est pas la cause. 5. **Page l'ingénieur d'astreinte si le symptôme côté utilisateur persiste après un redémarrage.** Pas besoin d'escalader plus tôt — la plupart des incidents se résolvent dans les trois premières étapes. ## Ce qui n'a pas besoin d'astreinte Une panne de `tale-knowledge-db` est un warn, pas un page. Le planning du crawl web absorbe des heures de downtime sans impact utilisateur, et l'ingestion de documents retente plutôt que de jeter le travail — les téléversements restent en « indexation » jusqu'au retour de la base du corpus. La recherche de connaissances renvoie vide entre-temps, mais les chats qui ne récupèrent pas de connaissances continuent de marcher. Attrape ça dans la bande warn et corrige-le pendant les heures de bureau. ## SLA de temps de réponse Deux budgets de temps de réponse sont suivis comme signaux de premier ordre : la saisie de dialogue interactive et les opérations longues comme les évaluations. Les deux sont vérifiés comme une **moyenne** sur une fenêtre glissante — le chiffre contractuel est une moyenne, pas un plafond par requête — et les deux sont câblés pour que Prometheus alerte dès que la moyenne dérive au-delà du budget. | Budget | Statistique | Cible | Fenêtre | Série sous-jacente | | ---------------- | ----------- | ----- | ------- | ----------------------------- | | Saisie dialogue | moyenne | ~1 s | 30 min | `tale_dialog_ttft_seconds` | | Opération longue | moyenne | ~40 s | 6 h | `tale_long_operation_seconds` | Chaque cible chevauche aussi l'endpoint de métriques de la plateforme sous `tale_sla_target_seconds{sla,statistic}`, pour qu'un panel Grafana trace la ligne de budget directement depuis Prometheus au lieu de la coder en dur. Les séries de latence sous-jacentes sont les histogrammes d'exécution de fonction Convex sur `/metrics/convex` ; relabel ou record-les vers les noms ci-dessus pour que les rules se résolvent. La plateforme sert les rules de recording et d'alerting prêtes à l'emploi sous `/metrics/sla-rules` (derrière le même bearer token que les autres chemins de métriques) — récupère-le une fois et référence le fichier sous `rule_files:`, ou colle l'équivalent : ```yaml groups: - name: tale-sla-recording rules: - record: tale_sla_dialog_ttft:mean30m expr: rate(tale_dialog_ttft_seconds_sum[30m]) / rate(tale_dialog_ttft_seconds_count[30m]) labels: sla: dialog_ttft - record: tale_sla_long_operation:mean6h expr: rate(tale_long_operation_seconds_sum[6h]) / rate(tale_long_operation_seconds_count[6h]) labels: sla: long_operation - name: tale-sla-alerts rules: - alert: TaleSlaDialogTtftBreached expr: tale_sla_dialog_ttft:mean30m > 1 for: 15m labels: severity: warn sla: dialog_ttft annotations: summary: 'Dialog input response time: mean response time over 30m exceeds the 1s SLA' description: Mean time-to-first-token for an interactive chat / dialog turn. - alert: TaleSlaLongOperationBreached expr: tale_sla_long_operation:mean6h > 40 for: 30m labels: severity: warn sla: long_operation annotations: summary: 'Long operation response time: mean response time over 6h exceeds the 40s SLA' description: Mean end-to-end time for long-running operations such as evaluations. ``` Un breach ici est un **warn**, pas un page : une moyenne qui dérive est une dégradation à traiter pendant les heures de bureau, et les fenêtres `for:` attendent délibérément qu'un pic court s'estompe avant de déclencher. Le budget dialogue de ~1 s se réconcilie avec le time-to-first-token chaud plus lâche de ~3 s du plan de performance manuel — ces ~3 s sont un plafond par requête pour un seul premier token froid, routé en Auto, temps modèle et réseau inclus, alors que les ~1 s ici sont la moyenne en régime permanent sur les tours de dialogue, donc des premiers tokens atteignant occasionnellement le plafond restent compatibles avec une moyenne sous la seconde. Tenir la moyenne de 1 s sur des fournisseurs live peut encore exiger l'optimisation du surcoût backend suivie sur l'issue de fonctionnalité ; cette alerte est ce qui confirme si la cible est atteinte. ## Où cela s'inscrit Les signaux ci-dessus sont le côté proactif d'opérer une instance Tale ; le côté réactif est [Dépannage](/fr/self-hosted/operate/observability/troubleshooting), et la configuration qui fait passer les métriques dans Prometheus est [Configuration de l'observabilité](/fr/self-hosted/configuration/observability-config). Si tu n'as pas encore réglé `METRICS_BEARER_TOKEN`, chaque seuil ci-dessus est non surveillé — commence par là. # Dépannage Source: https://tale.dev/docs/fr/self-hosted/operate/observability/troubleshooting Cette page est la recherche par symptôme quand quelque chose ne va pas, là, tout de suite. Chaque section commence par ce que l'utilisateur rapporte réellement — ce que le navigateur affiche, sur quoi l'agent échoue, ce que l'écran de téléversement dit — et remonte à la cause et au fix. Tout ce qui n'est pas listé ici est candidat pour une nouvelle section dès qu'il s'est présenté deux fois. Le côté proactif — signaux qui méritent une alerte, ce qu'il faut câbler à Prometheus — vit dans [Opérations](/fr/self-hosted/operate/observability/operations). Cette page est pour le moment après que la page a sonné. ## Le navigateur voit 502 ou « Bad Gateway » Le conteneur `tale-proxy` a joint la plateforme, mais la plateforme n'a pas répondu. Soit `tale-platform` est down, soit son endpoint de santé est injoignable. Vérifie l'état du conteneur en premier : ```bash docker compose ps tale-platform docker compose logs --tail=200 tale-platform ``` Si le conteneur redémarre, les logs en bas montrent la raison du crash — habituellement une variable d'env mal configurée (mismatch `SITE_URL`, `BETTER_AUTH_SECRET` manquant) ou un échec de connexion Postgres. Fix l'env, redémarre, réessaie. Si le conteneur est sain mais que le navigateur voit encore 502, le proxy est le suspect — `docker compose restart tale-proxy` règle la plupart. ## Le navigateur voit un avertissement TLS `TLS_MODE=selfsigned` est la cause la plus commune — le navigateur ne fait pas confiance à la CA interne de Caddy à la première visite. Soit fais confiance à la CA sur l'hôte (`docker exec tale-proxy caddy trust`), soit bascule sur `TLS_MODE=letsencrypt` pour un vrai certificat. Le walk complet des modes vit dans [TLS et domaines](/fr/self-hosted/configuration/tls-and-domains). Si le mode est déjà `letsencrypt`, vérifie les logs du proxy pour les échecs ACME — DNS qui ne résout pas vers l'IP publique de l'hôte et port 80 injoignable depuis l'Internet public sont les deux causes communes. ## L'UI charge mais aucune donnée n'apparaît Le shell UI sont des assets statiques servis par `tale-platform` ; tout le reste circule par `tale-convex` sur un WebSocket. Quand le WebSocket ne peut pas se connecter, le shell charge et reste vide. Symptômes : spinners qui ne se résolvent jamais, toasts « reconnecting », le champ de chat qui n'accepte jamais un message. ```bash docker compose logs --tail=200 tale-convex ``` Le conteneur convex redémarre probablement (cherche `panic` dans les logs) ou est injoignable depuis le proxy. Redémarre avec `docker compose restart tale-convex` — les sessions sont côté serveur et les clients se réabonnent à la reconnexion, donc le redémarrage est sûr. ## Téléversements bloqués en « indexation » L'ingestion de documents tourne dans le backend Convex et écrit les fragments extraits et les embeddings dans la base du corpus de connaissances. Un long état « indexation » signifie soit que le backend ne peut pas joindre `tale-knowledge-db`, soit que le fichier lui-même n'a pas pu être extrait. Vérifie les logs convex et la base du corpus en premier : ```bash docker compose logs --tail=200 tale-convex | grep -iE "knowledge|ingest|embed" docker compose ps tale-knowledge-db ``` Si les logs montrent des erreurs de connexion à `knowledge-db`, redémarre la base du corpus (`docker compose restart tale-knowledge-db`) ; l'ingestion retente à la passe suivante, donc les téléversements n'ont pas à être re-soumis. Si la base est saine mais qu'un téléversement spécifique est bloqué, le fichier lui-même est le suspect — les PDFs corrompus et les documents protégés par mot de passe atterrissent en état d'échec et exigent suppression + re-téléversement. ## Les réponses chat s'arrêtent au milieu du stream Le stream de tokens depuis le fournisseur amont est tombé — soit le fournisseur a rate-limité, soit la connexion a timeouté, soit le service du fournisseur est dégradé. Vérifie la page de statut du fournisseur d'abord ; puis regarde dans les logs plateforme : ```bash docker compose logs --tail=200 tale-platform | grep -E "429|503|stream" ``` Un `429` est le cas commun. Soit le budget de l'org touche le rate limit du fournisseur, soit la clé fournisseur elle-même est throttlée. Basculer le modèle par défaut de l'org sur un fournisseur moins chargé efface le symptôme pendant que l'amont refroidit. ## La sauvegarde échoue avec un toast « saving failed » Le conteneur convex n'a pas pu écrire dans Postgres. Soit `tale-db` est down, soit son disque est plein : ```bash docker compose ps tale-db docker compose exec db df -h /var/lib/postgresql/data ``` Un disque à 100 % est l'échec qui produit le plus de visages surpris. Libère de l'espace, redémarre `tale-db`, et les écritures en file flushent. Si le disque a de l'espace, le suspect est l'épuisement du pool de connexions ou un lock — redémarre `tale-convex` pour vider le pool. ## L'outil « Exécuter du code » échoue avec « egress denied » Le conteneur `tale-sandbox-egress` est le seul chemin réseau sortant pour le code en sandbox ; s'il est down ou mal configuré, chaque requête sortante de la sandbox échoue en mode fermé. Vérifie le conteneur egress d'abord : ```bash docker compose ps tale-sandbox-egress docker compose logs --tail=100 tale-sandbox-egress ``` Si le conteneur est sain et que tu as défini `SANDBOX_EGRESS_ALLOWLIST`, la requête a touché l'allowlist — étends la variable dans `.env` et recrée `tale-sandbox-egress`. Sans allowlist, le proxy est ouvert au niveau des hôtes ; vérifie plutôt la cible : seul le port 443 est tunnelisé pour HTTPS, et les adresses de métadonnées cloud et de plages privées sont toujours bloquées au niveau IP. ## Le sign-in revient en boucle à l'écran de sign-in `SITE_URL` ne correspond pas à ce que le navigateur a effectivement demandé. Les cookies d'auth sont scope sur l'URL où la requête a atterri ; un mismatch (slash en queue, port manquant, `http` vs `https`, préfixe base-path) signifie que le cookie posé au callback n'est pas envoyé à la prochaine requête. Fix `.env` : ```bash SITE_URL=https://tale.example.com # exactement ce que l'utilisateur tape ``` Recrée le conteneur plateforme (`docker compose up -d --force-recreate tale-platform`) pour que le changement atterrisse dans le HTML rendu. ## Où obtenir de l'aide Les instances auto-hébergées ne téléphonent pas à la maison, donc le support commence chez toi. Les deux canaux : - **GitHub Issues** — bugs et problèmes reproductibles. Le tracker [tale-project/tale](https://github.com/tale-project/tale/issues) a un template qui demande le bundle de diagnostics que `tale diagnostics` produit. - **Discord** — questions, débats de configuration, triage « est-ce un bug ». L'invitation vit dans le README du repo. Des diagnostics reproductibles rendent chaque canal plus rapide. `tale diagnostics` collecte les logs assainis, les variables d'env (secrets caviardés) et la santé des conteneurs dans une archive unique qui vaut la peine d'être attachée. # Prometheus et Grafana Source: https://tale.dev/docs/fr/self-hosted/operate/observability/prometheus-grafana C'est l'exemple mis en pratique derrière [Configuration de l'observabilité](/fr/self-hosted/configuration/observability-config) : une paire Prometheus et Grafana que tu poses à côté de Tale, pointée sur les deux endpoints de métriques à bearer token, avec un tableau de bord de départ et une règle d'alerte à étoffer. C'est pour les opérateurs auto-hébergés qui ont déjà défini `METRICS_BEARER_TOKEN` et veulent maintenant des graphes en direct plutôt qu'un `curl` contre `/metrics`. La page de référence de configuration liste les endpoints et la stanza de scrape unique ; cette page monte tout le stack de bout en bout. Tout ici tourne sur le même hôte que Tale, donc aucune métrique ne quitte la machine. ## Avant de commencer Définis `METRICS_BEARER_TOKEN` dans ton `.env` et redémarre le proxy — sans lui, les deux endpoints renvoient 401 à chaque requête, et Prometheus affichera chaque cible comme down. Les endpoints, et ce que chacun porte, sont le tableau dans [Configuration de l'observabilité](/fr/self-hosted/configuration/observability-config#metrics) : `/metrics/platform` et `/metrics/convex` (ce dernier porte désormais les timings RAG et de crawl en in-process), tous deux servis par `tale-proxy` sur le même nom d'hôte que l'app. ## Ajouter Prometheus et Grafana à ta stack Pose ces deux services dans un override compose à côté de Tale. Prometheus scrape à un intervalle et stocke une TSDB locale ; Grafana lit Prometheus et rend les tableaux de bord. Les deux se lient à localhost uniquement — atteins Grafana via un tunnel SSH ou mets-le derrière le même proxy avec auth, ne l'expose jamais brut. ```yaml # docker-compose.metrics.yml — start with: docker compose -f docker-compose.yml -f docker-compose.metrics.yml up -d services: prometheus: image: prom/prometheus:v3.1.0 volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro - prometheus-data:/prometheus ports: - '127.0.0.1:9090:9090' restart: unless-stopped grafana: image: grafana/grafana:11.4.0 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 volumes: prometheus-data: grafana-data: ``` ## Configuration du scraping Les deux endpoints de Tale partagent un bearer token, donc la config de scrape est la stanza publiée, répétée une fois par chemin. Enregistre ceci comme `prometheus.yml` à côté de l'override ci-dessus et substitue ton hôte et ton token — Prometheus lit le token depuis le fichier, garde-le donc en `chmod 600` et hors du contrôle de version. ```yaml global: scrape_interval: 30s scrape_configs: - job_name: tale-platform scheme: https metrics_path: /metrics/platform authorization: { credentials: '${METRICS_BEARER_TOKEN}' } static_configs: - targets: ['tale.example.com'] - job_name: tale-convex scheme: https metrics_path: /metrics/convex authorization: { credentials: '${METRICS_BEARER_TOKEN}' } static_configs: - targets: ['tale.example.com'] ``` Ouvre `http://127.0.0.1:9090/targets` après le démarrage — les deux jobs devraient afficher **UP**. Une cible bloquée en **DOWN** avec un 401 signifie que le token dans `prometheus.yml` ne correspond pas à `METRICS_BEARER_TOKEN` ; une erreur de connexion signifie que le nom d'hôte ou le schéma est faux. ## Un tableau de bord de départ Pointe d'abord Grafana sur Prometheus — ajoute une source de données Prometheus à `http://prometheus:9090` (Grafana l'atteint par le nom de service compose). Construis ensuite un tableau de bord à partir de ces panneaux ; les trois premiers utilisent des métriques toujours présentes, et le reste correspond aux signaux dans [Opérations](/fr/self-hosted/operate/observability/operations). | Panneau | Requête | Se lit comme | | ------------------- | ---------------------------------------------------- | --------------------------------------------------- | | Cibles up | `up{job=~"tale-.*"}` | `1` par endpoint sain, `0` quand le scraping échoue | | Mémoire plateforme | `process_resident_memory_bytes{job="tale-platform"}` | Mémoire résidente du conteneur platform | | Lag de l'event-loop | `nodejs_eventloop_lag_seconds{job="tale-platform"}` | Bondit quand la plateforme est saturée | | Convex up | `up{job="tale-convex"}` | Joignabilité du backend — `0` est un page | L'endpoint platform porte les métriques de processus par défaut de Node (CPU, mémoire, lag de l'event-loop, GC), c'est pourquoi les requêtes concrètes ci-dessus le ciblent. L'endpoint Convex expose sa propre série plus riche, dont les timings RAG et de crawl en in-process — ouvre-le une fois (`curl -H "Authorization: Bearer $TOKEN" https://tale.example.com/metrics/convex`) pour lire les noms de métriques exacts qu'expose ta version, puis ajoute des panneaux pour le débit d'ingestion de connaissances et le taux d'erreur fournisseur évoqués dans Opérations. ## Une première règle d'alerte Commence par le seul signal sans ambiguïté — une cible de métriques qui cesse de répondre. Ajoute ce fichier de règle à Prometheus (monte-le et référence-le sous `rule_files:` dans `prometheus.yml`), puis câble Alertmanager ou l'alerting Grafana sur ton pager. ```yaml 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' ``` La liste complète de ce qui vaut un page contre ce qui peut attendre — taux de 5xx de la plateforme, saturation du pool Postgres, joignabilité de la base de connaissances, sauvegarde-quotidienne-non-écrite — est le tableau de signaux dans [Opérations](/fr/self-hosted/operate/observability/operations) ; traduis chaque ligne en règle dès que la série correspondante est sur ton tableau de bord. ## Où cela s'inscrit Cette page transforme les deux endpoints de métriques documentés en un stack Prometheus et Grafana qui tourne : un override compose, une config de scrape à deux jobs, un tableau de bord de départ et une alerte cible-down que tu étoffes avec les seuils d'Opérations. Garde les deux services liés à localhost et le bearer token hors du disque en clair, et toute la surface de monitoring reste sur l'hôte avec Tale. Les endpoints et le token qui les protège appartiennent à [Configuration de l'observabilité](/fr/self-hosted/configuration/observability-config) ; les seuils et la checklist d'astreinte sont [Opérations](/fr/self-hosted/operate/observability/operations). Quand un panneau passe au rouge, la recherche symptôme-vers-correction est [Dépannage](/fr/self-hosted/operate/observability/troubleshooting). # Montées de version Source: https://tale.dev/docs/fr/self-hosted/operate/upgrades Les montées de version sur une instance Tale auto-hébergée passent par deux commandes : `tale update` bouge le binaire CLI à la nouvelle version et synchronise tes fichiers projet pour correspondre, puis `tale deploy` roule les conteneurs plateforme. Le déploiement utilise un pattern blue-green — la nouvelle couleur démarre à côté de l'ancienne, les healthchecks passent, le trafic bascule, l'ancienne couleur draine. Zéro downtime est le défaut ; si une release patch se comporte mal, `tale rollback` ramène le patch précédent en une commande, et tout ce qui est plus gros se récupère depuis le snapshot pré-upgrade. Ce que tu ne fais plus, c'est garder la CLI synchronisée à la main : la CLI s'aligne elle-même sur l'instance automatiquement (voir plus bas), donc le seul pas délibéré est de choisir quand bouger de version avec `tale update`. L'installation de la CLI vit dans [Installer la CLI tale](/fr/self-hosted/install/cli-install). Cette page couvre ce que fait chaque commande et comment le modèle de versions fonctionne. ## La CLI suit l'instance automatiquement Le binaire CLI est toujours à la même version que l'instance qu'il gère. Le workspace enregistre cette version dans `tale.json` ; à chaque commande, la CLI compare sa propre version à celle-là et, si elles diffèrent, se met à jour pour correspondre (en montant ou en descendant) avant de tourner. Quand elles correspondent déjà — le cas largement le plus fréquent — c'est un no-op sans appel réseau, donc tu ne le remarques jamais. Cela veut dire que tu lances rarement `tale update`, sauf quand tu veux délibérément bouger vers une nouvelle version. Un coéquipier qui a installé une CLI plus récente que ton instance, ou restauré un snapshot plus ancien, obtient la bonne version de CLI automatiquement à sa prochaine commande. Il n'y a aucun flag pour désactiver ça — garder l'outil et l'instance au pas l'un de l'autre est ce qui rend les déploiements sûrs. ## Avant de monter de version Deux choses valent la peine d'être confirmées d'abord : - Ta copie hors-hôte du volume `backups` est à jour — voir [Backups et restauration](/fr/self-hosted/operate/backups-and-restore). `tale update` snapshotte automatiquement les volumes de données avant toute étape qui peut migrer des données, mais le snapshot vit sur le même hôte ; la copie hors-hôte est ce qui survit à un disque mort. - Les notes de version pour la version cible ne nomment pas un changement breaking. Les notes sont liées depuis la page de release GitHub ; les changements breaking sont flaggés comme tels en haut. Si la montée de version traverse une version majeure (1.x → 2.x), lis les notes de migration de bout en bout avant de commencer. Les versions majeures sont où atterrissent les migrations de schéma et les changements de format de fichier de config. ## Les deux commandes `tale update` met à jour le binaire CLI, puis synchronise tes fichiers projet sur les templates de cette version. Il ne **touche pas** aux conteneurs en marche — c'est le boulot de `tale deploy`. Si la synchro des fichiers échoue, la CLI fait reculer son propre binaire à la version sur laquelle ton workspace était, pour que le binaire et `tale.json` ne dérivent jamais l'un de l'autre. ```bash # Bouge la CLI et les fichiers projet à la dernière release tale update # Fixe une version précise (autorise les downgrades — voir Rollback) tale update --version 0.10.2 # Aperçu du changement de version et de la synchro des fichiers sans rien toucher tale update --dry-run ``` `tale deploy` fait le vrai redémarrage rolling, et il déploie toujours la version propre à la CLI — qui, grâce à l'alignement, est la version qu'enregistre ton workspace. Il trie les services en trois étages : - **Étage app** — `platform` — roule à **chaque** déploiement, sans downtime (blue-green : la nouvelle couleur démarre à côté de l'ancienne, les healthchecks passent, le trafic bascule, l'ancienne couleur draine). - **Backend et compute** — `convex`, `sandbox`, `sandbox-egress` — roulent à chaque déploiement eux aussi, pour ne jamais dériver en version d'avec `platform`. Chacun est un conteneur unique qui se recrée **en place** quand son image a réellement changé ; le déploiement draine d'abord le travail en cours (générations de chat pour `convex`, runs d'agent pour `sandbox`) pour que le bref redémarrage ne coupe pas une requête en vol. - **Étage à arrêt requis** — `db`, `proxy` — laissés **en marche et intacts** par défaut (recréer Postgres ou le proxy est une brève coupure que tu ne veux pas sur un roll de routine). Passe `--stop` pour les mettre à jour ; le déploiement prévient et les nomme quand il les saute. ```bash # Après tale update, roule les conteneurs pour correspondre (étage app + convex) tale deploy # Mets aussi à jour db/proxy (brève coupure pendant qu'ils se recréent) tale deploy --stop # Roule seulement des services spécifiques tale deploy --services platform # Aperçu sans changement tale deploy --dry-run ``` `--dry-run` mérite d'être lancé avant chaque montée de version en production — il fait remonter les images manquantes, les migrations manquantes et les mismatches de dépendances sans toucher aux conteneurs en marche. ## Le pattern blue-green Une instance en marche est l'une des deux couleurs (blue ou green) à un instant donné. La phase de déploiement monte l'autre couleur, attend qu'elle passe les healthchecks, puis bascule l'upstream de Caddy sur la nouvelle couleur. L'ancienne couleur draine ses requêtes en vol (défaut 30 s), puis sort. Trois garanties que le pattern te donne : - **Aucune fenêtre où les deux couleurs servent du trafic.** Un constraint de base impose single-active — Caddy route vers la saine. - **Le rollback de patch est une commande.** `tale rollback` redéploie la release patch précédente sur la couleur inactive et rebascule le trafic. Il refuse les downgrades minor et major — ceux-là peuvent laisser la base en avance sur le binaire, et leur chemin de récupération est une restauration de snapshot. - **Les healthchecks échoués bloquent la bascule.** Si la nouvelle couleur ne passe pas dans le timeout, le déploiement abandonne et l'ancienne couleur continue à servir. La procédure complète de déploiement, y compris la phase de cleanup, vit dans `tale --help` ; la recette côté opérateur est `tale update && tale deploy && tale status` et confirmation visuelle dans le navigateur. ## Travailler avec les migrations de données Chaque déploiement applique automatiquement les migrations de données en attente — mais seulement celles qui ne détruisent rien. Les migrations qui suppriment ou écrasent des données (suppression d'une table, retrait d'une colonne) ne tournent jamais sans surveillance : le déploiement les saute, affiche celles qui attendent et vous laisse la décision. ```bash # Ce qui est appliqué, en attente, en échec tale migrate status # Appliquer les migrations en attente, en validant chaque étape destructrice tale migrate up --step # Tout appliquer sans confirmation (CI / après revue du plan) tale migrate up --yes # Ramener les données à une version antérieure tale migrate down --to 0.3.3 ``` Les migrations destructrices sauvegardent les lignes ou fichiers de configuration concernés avant d'y toucher : `tale migrate down` peut ainsi reconstruire ce qu'elles ont retiré. Les deux sens sont reprenables : la progression est suivie par migration (et par organisation pour les migrations de fichiers de configuration), un crash ou un timeout reprend donc là où il s'était arrêté. Si une migration échoue pendant un déploiement, la plateforme démarre quand même sur son schéma actuel — le journal de démarrage affiche une erreur bien visible et `tale migrate status` montre la migration en échec avec son message. Corrigez la cause, puis relancez `tale migrate up` ; le travail déjà accompli est sauté. ## Rollback ```bash # Retour à la version patch précédente (demande confirmation) tale rollback # Ignorer l'invite en mode non-interactif tale rollback --yes ``` `tale rollback` est limité aux pas de patch : il ne cible que la version précédente enregistrée, et refuse si cette version ne partage pas `major.minor` avec la plateforme qui tourne. Les releases patch ne portent jamais de migrations, donc redéployer le patch précédent est toujours sûr. Tout ce qui est plus gros peut avoir migré les données vers l'avant — déployer un binaire plus vieux sur des données migrées corrompt l'instance au lieu de la sauver. Pour ces cas, le chemin de récupération est de restaurer le snapshot pré-upgrade et de revenir à la version qui lui correspond avec `tale update --version <version>` suivi de `tale deploy --stop` (pour que `db`/`proxy` reculent aussi) ; le message de refus imprime les commandes exactes, et le walk complet vit dans [Backups et restauration](/fr/self-hosted/operate/backups-and-restore). Comme le rollback démolit les conteneurs en cours d'exécution, la commande prévient de ce qu'elle s'apprête à faire et demande confirmation avant de tirer la moindre image ; passe `--yes` pour ignorer cette invite dans les scripts ou en CI. ## Compatibilité de versions Les versions Tale sont en semver. Les règles de compatibilité : - Patch (`0.9.0 → 0.9.1`) — pas de migrations, pas de changements de config, `tale rollback` est toujours sûr. - Minor (`0.9.x → 0.10.x`) — peut inclure des migrations forward-only ; `tale rollback` refuse, la récupération est restauration-de-snapshot plus redéploiement. - Major (`0.x → 1.x`) — lis les notes de migration, planifie la fenêtre de maintenance, attends-toi à des surprises. Sauter des versions mineures (passer de 0.9 à 0.11) est supporté tant que les migrations intermédiaires sont encore dans le binaire ; les notes de version le mentionnent quand ce n'est pas le cas. Pour descendre _délibérément_ d'une version — disons qu'une release minor se comporte mal et que tu as déjà inversé ses migrations — fixe la cible avec `tale update --version <version>`. La commande prévient quand la cible est plus ancienne que la version qui tourne et te rappelle d'inverser d'abord les migrations de données. ## Monter depuis la 0.3.1 ou antérieure Les instances en version 0.3.1 ou antérieure gardent les données du backend Convex dans le volume Docker `platform-data`. Les versions plus récentes font tourner Convex comme service à part entière avec son propre volume `convex-data` — et rien ne déplace les données automatiquement au déploiement. Franchis cette frontière d'un coup et `tale deploy` pré-crée un volume `convex-data` **vide** : l'instance démarre vierge alors que chaque octet de tes données reste, intact, dans l'ancien volume `platform-data`. Rien n'est supprimé — mais les données ne bougent pas toutes seules, et `tale update` avertit quand il détecte cette situation et te propose de lancer la copie sur-le-champ. Docker n'a pas de renommage natif de volume ; le déménagement passe donc par une copie via un conteneur intermédiaire — exactement ce que `tale update` exécute pour toi quand tu acceptes son invite (l'ancien volume est préservé dans tous les cas). Pour le faire à la main — invite refusée, ou copie automatique en échec — exécute-la avant `tale deploy`, stack arrêtée, pour que rien ne garde le volume ouvert : ```bash # 1. Repérer le volume legacy — <project> est l'`id` de tale.json. docker volume ls | grep platform-data # Les installations antérieures à la 0.2.33 utilisaient le préfixe # fixe `tale_` au lieu de `<project>_` ; la destination ci-dessous # garde `<project>_`. # 2. Arrêter la stack. docker compose -p <project> down # 3. Créer le volume de destination et copier les données. docker volume create <project>_convex-data docker run --rm \ -v <project>_platform-data:/from:ro \ -v <project>_convex-data:/to \ alpine sh -c "cd /from && cp -a . /to" # 4. Rouler la stack, puis vérifier que tes données sont là. tale deploy # 5. Une fois vérifié seulement, récupérer l'espace de l'ancien volume. docker volume rm <project>_platform-data ``` Un workspace de dev suit le même déménagement sous le scope `-dev` : `<project>-dev_platform-data` → `<project>-dev_convex-data`, avec `docker compose -p <project>-dev down` comme étape d'arrêt. Si tu as déjà déployé et obtenu une instance vide, tes données sont toujours en sécurité dans `platform-data`. Arrête la stack, supprime le volume vide fraîchement créé avec `docker volume rm <project>_convex-data`, puis exécute la copie ci-dessus et redéploie. ## Où cela s'inscrit Le flow de montée de version noue chaque autre page d'exploitation — les backups sont ce qui rend une montée de version échouée récupérable, l'observabilité est ce qui te dit que la nouvelle couleur est saine, le durcissement est ce que tu reparcours après une version majeure. Si tu mets en place la CLI pour la première fois, [Installer la CLI tale](/fr/self-hosted/install/cli-install) couvre le setup côté workstation ; si tu prends le pager en plein rollout, [Dépannage](/fr/self-hosted/operate/observability/troubleshooting) nomme les symptômes. # Résidence des données Source: https://tale.dev/docs/fr/self-hosted/configuration/data-residency Une installation Tale auto-hébergée tourne sur une infrastructure que tu contrôles déjà, donc ses données vivent sur tes hôtes par défaut. La **résidence des données** sert au cas où tu veux pointer des banques de données précises vers ton propre Postgres géré ou ton stockage objet plutôt que vers les conteneurs fournis — par exemple pour garder le texte des documents dans une base que ton équipe exploite, ou les fichiers téléversés dans ton propre bucket S3. Le corpus de connaissances tourne comme son propre conteneur (`knowledge-db`) précisément pour pouvoir être relocalisé ou remplacé indépendamment de la base opérationnelle — c'est la banque qui compte le plus pour la majorité des exigences de résidence. Les administrateurs configurent cela dans **Paramètres > Résidence des données** ; le changement est écrit dans un seul fichier de configuration au niveau du déploiement et **prend effet au redémarrage des conteneurs concernés**. Cette page couvre ce qui peut être déplacé, le seul prérequis qui mord (ParadeDB), comment la configuration est stockée et appliquée, et comment redémarrer sans risque. ## Activer la modification Voir la page est ouvert à tout owner ou admin d'une organisation, mais **modifier** — repointer une banque de données, enregistrer des secrets, lancer un test de connexion ou appliquer un redémarrage — est réservé à une allowlist nommée d'opérateurs. Liste leurs courriels de connexion (séparés par des virgules) dans `.env` et redémarre : ```bash TALE_DEPLOYMENT_CONFIG_ADMINS=alice@example.com,bob@example.com ``` Si l'allowlist est vide ou non définie, **Paramètres > Résidence des données** montre toujours la configuration actuelle aux administrateurs, mais en lecture seule — Enregistrer, Tester et Appliquer & redémarrer refusent pour tout le monde. Seul un admin connecté dont le courriel figure sur la liste obtient une page modifiable ; la page t'indique quel courriel ajouter. Les entrypoints consomment le fichier de configuration quelle que soit l'allowlist, donc un opérateur qui préfère éditer le fichier à la main sur le disque peut le faire sans nommer d'éditeurs UI. ## Ce que tu peux relocaliser Trois banques de données, chacune indépendante et optionnelle. Un réglage absent signifie « utilise le défaut fourni » — une installation neuve sans configuration reste donc inchangée. - **Base de connaissances** — le corpus de connaissances : métadonnées des documents, texte des fragments extraits, embeddings, index BM25, cache sémantique et pages web crawlées. Elle est livrée comme le conteneur `knowledge-db` (`tale_knowledge`, avec les schémas `private_knowledge` et `public_web`) et c'est la banque qui compte le plus pour les exigences de résidence, car elle détient le contenu de tes documents. Pointe-la vers ton propre Postgres géré pour garder le corpus sur une infrastructure que ton équipe exploite. - **Stockage de fichiers** — où vivent les fichiers téléversés (les blobs d'origine). Par défaut ils résident sur le volume Convex local ; tu peux les pointer vers un bucket externe compatible S3. - **Base de données applicative** (avancé) — la base Convex opérationnelle (le conteneur `db` fourni). Le backend Convex déduit le nom de cette base de `INSTANCE_NAME` (`tale_platform`) et se connecte uniquement via hôte:port, donc le Postgres externe doit contenir une base nommée exactement `tale_platform`. Son mode TLS est fixé par le pilote Convex et n'est pas configurable. > Note : la base de connaissances et la base de données applicative sont deux instances Postgres séparées — déplacer l'une ne touche pas l'autre. Relocaliser la base de connaissances déplace le texte extrait et les embeddings ; les fichiers téléversés d'origine ne suivent que si tu relocalises aussi le **stockage de fichiers** vers S3. ## Le prérequis ParadeDB La base de connaissances utilise deux extensions Postgres : `vector` (pgvector) pour les embeddings et `pg_search` (ParadeDB) pour la recherche hybride plein texte/BM25. Un Postgres de connaissances externe **doit faire tourner ParadeDB** (qui regroupe les deux) pour une qualité de recherche complète. Si tu le pointes vers un Postgres simple qui n'a que `pgvector`, l'indexation et la recherche vectorielle fonctionnent toujours, mais la recherche hybride se réduit à du **vectoriel seul** — la moitié BM25 est silencieusement sautée. Le bouton **Tester la connexion** signale la disponibilité de `pgvector` et de `pg_search` pour que tu le voies avant de t'engager. La base de connaissances externe doit déjà exister (elle peut porter n'importe quel nom que tu saisis — `tale_knowledge` par convention) avec les schémas `private_knowledge` et `public_web` ; les migrations de schéma de base vivent dans [`services/db/migrations/`](https://github.com/tale-project/tale/tree/main/services/db/migrations) et sont appliquées via dbmate quand la base démarre. ## Stockage de fichiers sur S3 Le stockage de fichiers externe est tout-ou-rien à travers les cas d'usage de stockage de Convex, donc tu fournis **cinq buckets** — files, exports, snapshot-imports, modules et search — plus une région et des identifiants. Pour les services compatibles S3 (MinIO, Cloudflare R2), définis l'endpoint et active l'adressage path-style. > **Greenfield uniquement.** Faire passer le stockage de fichiers de local à S3 ne migre **pas** les blobs déjà sur le volume local — Convex les cherche dans le bucket et ne les trouve pas. Définis S3 au déploiement initial, ou copie le stockage local existant dans le bucket hors bande avant de basculer. ## Comment la configuration est stockée Enregistrer écrit deux fichiers à la racine de configuration (pas sous un répertoire d'org) : - `deployment.json` — la configuration non secrète (hôtes, ports, buckets, modes). - `deployment.secrets.json` — les mots de passe de base de données et les clés S3, chiffrés avec SOPS (voir [Secrets avec SOPS](/fr/self-hosted/configuration/secrets-with-sops)). Au démarrage, l'entrypoint `convex` les lit et en dérive ses connexions avant de démarrer. L'ingestion et la récupération de connaissances tournent dans le backend Convex, c'est donc le seul conteneur qui ouvre la connexion à la base de connaissances — il n'y a pas de service de récupération séparé à configurer. Le contrat est **fail-closed** : un `deployment.json` présent mais impossible à parser, un secret indéchiffrable ou une configuration sans champs requis **interrompt le démarrage** au lieu de retomber silencieusement sur la base fournie — mal router des données réglementées est pire que ne pas démarrer. Un fichier absent est le chemin par défaut normal. ## Appliquer un changement : redémarrage La configuration est lue au démarrage, donc un enregistrement ne prend effet qu'au redémarrage du conteneur **`convex`** (la plateforme elle-même n'a pas besoin de redémarrer). Deux façons : - **Manuel** — `docker compose restart convex`, ou `tale deploy --services convex` pour un roulement blue-green sans interruption. - **Un clic** — active le service `controller` à activer explicitement (`docker compose --profile controller up -d`). C'est un petit sidecar uniquement interne qui redémarre le service `convex` autorisé sur une requête signée par HMAC venant de l'app, pour que la plateforme exposée au navigateur n'ait jamais besoin d'accéder au socket Docker. Quand il tourne, le bouton **Appliquer & redémarrer** fait le redémarrage pour toi ; définis `CONTROLLER_TOKEN` (partagé avec la plateforme) et `CONTROLLER_URL` dans `.env`. Sans lui, le bouton montre la commande manuelle. Les variables d'environnement pertinentes sont `TALE_DEPLOYMENT_CONFIG_ADMINS` (l'allowlist de courriels, séparés par des virgules, des opérateurs autorisés à modifier) et — seulement avec le `controller` en un clic — `CONTROLLER_TOKEN` (le secret HMAC partagé) et `CONTROLLER_URL` (p. ex. `http://controller:8004`). Définis-les dans `.env`. Voir aussi [Référence des variables d'environnement](/fr/self-hosted/configuration/environment-reference) et [Secrets avec SOPS](/fr/self-hosted/configuration/secrets-with-sops). # TLS et domaines Source: https://tale.dev/docs/fr/self-hosted/configuration/tls-and-domains Le conteneur `tale-proxy` est Caddy. Il possède la terminaison TLS, le routage par hôte et la barrière d'auth des métriques ; chaque requête venue du navigateur y atterrit en premier. Les trois modes — auto-signé, Let's Encrypt, externe — couvrent les trois formes de déploiement que la plupart des opérateurs choisissent, et la variable qui bascule entre eux est `TLS_MODE` dans ton `.env`. Les lignes de référence des variables d'env vivent dans [Référence des variables d'environnement](/fr/self-hosted/configuration/environment-reference#tls). Cette page est le walkthrough mode par mode et les recettes pour les domaines personnalisés et bring-your-own certificats. ## Auto-signé (défaut) `TLS_MODE=selfsigned` fait tourner Caddy avec un certificat qu'il génère depuis sa CA interne. Le navigateur avertit la première fois, et l'hôte doit faire confiance au certificat pour supprimer l'avertissement — c'est destiné au développement local : ```bash docker exec tale-proxy caddy trust ``` La commande trust importe la CA de Caddy dans le trust store système sur l'hôte qui fait tourner le démon Docker. Les autres machines du réseau voient encore l'avertissement sauf si elles importent la CA aussi. La production n'utilise jamais ce mode. ## Let's Encrypt `TLS_MODE=letsencrypt` laisse Caddy émettre et renouveler un vrai certificat public. Trois prérequis doivent tenir sinon la boucle d'émission échoue : - Le hostname dans `HOST` et `SITE_URL` résout vers l'IP publique de l'hôte depuis l'Internet public. - Les ports 80 et 443 sont joignables depuis l'Internet public (le port 80 porte le challenge ACME HTTP-01). - `TLS_EMAIL` est mis sur une boîte mail que tu lis — Let's Encrypt y avertit avant l'expiration. ```bash # .env TLS_MODE=letsencrypt TLS_EMAIL=ops@yourdomain.com ``` Le premier boot bloque environ une minute pendant que le challenge ACME tourne. Après ça, les renouvellements sont automatiques 30 jours avant l'expiration ; les échecs atterrissent dans `docker compose logs proxy`. ## Proxy externe `TLS_MODE=external` fait que Caddy sert du HTTP en clair à l'intérieur, et tu le mets derrière ton propre reverse proxy qui termine TLS en amont. Choisis ça quand : - Tu fais déjà tourner un CDN ou un load balancer qui gère les certificats. - Tu veux terminer TLS une seule fois au bord de ton VPC et faire tourner tout l'interne en clair. - Ta posture de compliance exige une autorité de certification spécifique que Caddy ne supporte pas. ```bash # .env TLS_MODE=external SITE_URL=https://tale.yourdomain.com # l'URL que tes utilisateurs frappent ``` Le proxy en amont a besoin que `X-Forwarded-Proto: https` soit posé sur chaque requête pour que Tale génère des redirects et des URL absolues correctes. Sans lui, les liens de sign-in atterrissent sur `http://` et le flag `Secure` du cookie d'auth les rejette. ## Domaine personnalisé Le domaine lui-même n'est que `HOST` et `SITE_URL`. Le même Caddyfile dans `tale-proxy` lit les deux au boot. Change-les, recrée le conteneur proxy (`docker compose up -d --force-recreate tale-proxy`), et le nouveau domaine est live en quelques secondes. Let's Encrypt réémet pour le nouveau nom à la prochaine requête qui frappe le nouveau hostname. ```bash # .env HOST=tale.example.com SITE_URL=https://tale.example.com ``` Les déploiements en sous-chemin — Tale derrière `https://example.com/app/` — règlent en plus `BASE_PATH=/app`. Le reverse proxy en amont de Caddy ne strip rien ; Tale gère le préfixe lui-même. ## Apporter ton propre certificat Pour une CA interne ou un certificat wildcard que tu possèdes déjà, monte le certificat et la clé dans `tale-proxy` et ajoute une directive `tls` au Caddyfile : ```yaml # override compose.yml services: proxy: volumes: - ./certs/fullchain.pem:/etc/tale/cert.pem:ro - ./certs/privkey.pem:/etc/tale/key.pem:ro environment: TLS_MODE: external # contourne l'auto-émission de Caddy ``` Ensuite, soit pré-construis une image `tale-proxy` avec un Caddyfile personnalisé, soit mets ton propre reverse proxy devant Tale et reste sur `TLS_MODE=external` — les deux chemins sont supportés et le second est plus simple. ## Où cela s'inscrit Les trois modes couvrent les trois formes de déploiement que la plupart des équipes touchent ; les lignes de variables d'env vivent dans [Référence des variables d'environnement](/fr/self-hosted/configuration/environment-reference#tls). Si tu mets en place un hôte de production frais maintenant, [Installation serveur Linux de production](/fr/self-hosted/install/linux-server) walk Let's Encrypt de bout en bout avec les étapes firewall et DNS dans l'ordre. # Référence des variables d'environnement Source: https://tale.dev/docs/fr/self-hosted/configuration/environment-reference Tale lit sa configuration depuis un unique fichier `.env` à la racine du dépôt. Environ une douzaine de variables sont obligatoires au premier boot ; les autres ajustent le comportement. Cette page liste chaque variable que [`.env.example`](https://github.com/tale-project/tale/blob/main/.env.example) ship, sa valeur par défaut et la surface produit qui la consomme. Les groupes sont ordonnés selon le moment où tu en as besoin la première fois : identité de domaine, TLS, secrets, base de données, instance, observabilité, chiffrement des fournisseurs. Si une variable change de valeur, redémarre le conteneur plateforme (`docker compose restart tale-platform tale-convex`) pour qu'elle prenne effet. ## Comment lire cette page Chaque groupe est un tableau `Nom | Défaut | Description`. Les variables marquées **Obligatoire** doivent être définies pour que `docker compose up` réussisse. Les variables marquées **Optionnel** peuvent rester non définies ; la description nomme ce que désactiver la fonctionnalité signifie. Le fichier `.env.example` ship des commentaires inline qui expliquent chaque variable dans son contexte ; cette page est la référence structurée et groupée pour le même ensemble. ## 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. | | `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. | Le `SITE_URL` doit correspondre exactement à ce que l'utilisateur tape dans le navigateur. Un slash en queue, un port manquant ou `http` au lieu de `https` cassent le callback d'auth et produisent des boucles de sign-in. ## TLS | Nom | Défaut | Description | | ----------- | ------------ | --------------------------------------------------------------------------------------------------------------------- | | `TLS_MODE` | `selfsigned` | Un de `selfsigned`, `letsencrypt`, `external`. Voir [TLS et domaines](/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. | `selfsigned` fait tourner Caddy avec un certificat généré — le navigateur avertit, OK pour le développement. `letsencrypt` exige un vrai domaine et les ports 80/443 joignables depuis l'Internet public. `external` fait servir Caddy en HTTP brut ; un reverse proxy amont termine TLS. ## Secrets de sécurité (obligatoire) | Nom | Défaut | Description | | ----------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BETTER_AUTH_SECRET` | valeur d'exemple dans le fichier | **Obligatoire.** Secret base64 pour le signeur de session Better Auth. Génère avec `openssl rand -base64 32`. La rotation invalide chaque session. | | `ENCRYPTION_SECRET_HEX` | valeur d'exemple dans le fichier | **Obligatoire.** Clé hex de 32 octets. Clé AES-256 pour les credentials OAuth et intégrations et entrée HKDF pour la secret-box des garde-fous. Génère avec `openssl rand -hex 32`. La rotation invalide chaque ciphertext en base ; les opérateurs doivent réinscrire les secrets concernés. | | `INSTANCE_SECRET` | valeur d'exemple dans le fichier | **Obligatoire.** Sert à dériver la clé admin Convex pour `tale deploy`. Le déploiement échoue si non défini. | 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 fait tourner deux bases Postgres : la base opérationnelle (`db`, port 5432) derrière le backend Convex, et le corpus de connaissances (`knowledge-db`, port 5433) qui détient les fragments de documents, les embeddings et les pages crawlées. Les deux sont ParadeDB et partagent `DB_PASSWORD`, mais elles sont indépendantes — pointe l'une ou l'autre vers une infrastructure externe séparément. | Nom | Défaut | Description | | ------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DB_PASSWORD` | `tale_password_change_me` | **Obligatoire.** Mot de passe pour l'utilisateur Postgres auto-hébergé. Change-le avant la production. Utilisé par les deux conteneurs de base de données. | | `POSTGRES_URL` | construit depuis `DB_PASSWORD` | **Optionnel.** Override de l'URL de la base opérationnelle construite automatiquement. Utilise-le pour pointer sur un Postgres externe ou un hôte/port non standard. | | `KNOWLEDGE_DATABASE_URL` | `postgresql://tale:${DB_PASSWORD}@knowledge-db:5432/tale_knowledge` | **Optionnel.** URL de connexion que le backend Convex utilise pour le corpus de connaissances. Override pour relocaliser le corpus vers ton propre ParadeDB géré — la banque sensible à la résidence se déplace indépendamment. | | `KNOWLEDGE_DB_NAME` | `tale_knowledge` | **Optionnel.** Nom de la base de connaissances. Le conteneur `knowledge-db` fourni crée cette base au premier boot. | La forme opérationnelle auto-construite est `postgresql://tale:${DB_PASSWORD}@db:5432`. Convex attend cette URL sans nom de base ; le nom est dérivé de la configuration d'instance. Le corpus de connaissances vit dans `tale_knowledge` avec les schémas `private_knowledge` et `public_web` ; l'UI **Paramètres > Résidence des données** écrit une config par banque plus riche que ces variables brutes, couverte dans [Résidence des données](/fr/self-hosted/configuration/data-residency). ## 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_TRACES_SAMPLE_RATE` | non défini | Taux d'échantillonnage optionnel pour les traces de performance (`0.0`–`1.0`). Le comportement par défaut dépend du déploiement. | | `METRICS_BEARER_TOKEN` | non défini | Token bearer requis pour accéder aux endpoints Prometheus `/metrics/*`. Laisse vide pour rendre les endpoints inatteignables de l'extérieur. | Définir `METRICS_BEARER_TOKEN` expose deux endpoints derrière le token : `/metrics/platform` et `/metrics/convex` (les 261 métriques intégrées de Convex, qui portent désormais aussi les timings RAG et de crawl). Voir [Configuration d'observabilité](/fr/self-hosted/configuration/observability-config) pour la configuration de scrape. ## Chiffrement des secrets de fournisseur | Nom | Défaut | Description | | ------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SOPS_AGE_KEY` | non défini | Clé secrète age inline. Chiffre `providers/*.secrets.json`. Mode par défaut après `tale init`. Plusieurs clés ne sont pas supportées en inline. | | `SOPS_AGE_KEY_FILE` | non défini | Chemin vers un fichier avec une ou plusieurs clés age (une par ligne ; commentaires `#` autorisés). Obligatoire pour la rotation. S'exclut mutuellement avec la forme inline. | Si les deux clés age ne sont pas définies, Tale stocke `providers/*.secrets.json` en JSON clair en mode 0600. Atteins ce mode seulement si le disque hôte est chiffré au repos ou si les fichiers sont produits par un outillage externe (un montage de secret Kubernetes, un template Vault). Faire tourner une clé age, c'est ajouter la nouvelle clé, réenregistrer chaque fournisseur dans l'UI, puis retirer l'ancienne. Voir [Secrets avec SOPS](/fr/self-hosted/configuration/secrets-with-sops) pour la marche complète de rotation. La source de clé par variable d'environnement ne nécessite aucun commutateur de déploiement : un fournisseur peut lire sa clé depuis une variable d'environnement plutôt que depuis un fichier de secrets, tant que la variable est nommée avec le préfixe réservé `TALE_PROVIDER_KEY_` (tout autre nom est rejeté). Le mécanisme — la barrière de préfixe, l'ordre de résolution, le plafond de 40 caractères, l'exigence de redémarrage — est documenté dans [Fournisseurs](/fr/self-hosted/configuration/providers#environment-variable-key-source). Une [source de jetons](/fr/platform/admin/token-sources) suit le même schéma pour le secret d'auth du courtier qu'elle lui envoie : elle lit depuis un sidecar chiffré `token-sources/<slug>.secrets.json`, ou depuis une variable d'environnement nommée avec le préfixe réservé `TALE_TOKEN_SOURCE_` (tout autre nom est rejeté, donc le champ ne peut jamais pointer sur un secret de déploiement). La variable est par source ; définis-la ici ou dans ton gestionnaire de secrets pour que la plateforme et le backend Convex puissent tous deux la lire. ## Drapeaux de fonctionnalité Bascules optionnelles pour des fonctionnalités non activées par défaut. Chaque drapeau active ou désactive une fonctionnalité au boot ; basculer demande un redémarrage du conteneur plateforme. | Nom | Défaut | Description | | ------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `TRUSTED_HEADERS_ENABLED` | `false` | Active le mode auth par trusted headers (identité fournie par le reverse proxy). | | `FILE_EVENTS_ENABLED` | `false` | Active les événements de surveillance de fichiers pour l'intégration OneDrive-sync. | | `TALE_DEPLOYMENT_CONFIG_ADMINS` | non défini | Allowlist de courriels (séparés par des virgules) des opérateurs autorisés à modifier la résidence des données du déploiement. Vide/non défini = lecture seule pour tous les admins. | ## Réglage du retrieval RAG Réglages optionnels pour la recherche dans la base de connaissances. Le chemin RAG en in-process (node-actions Convex) re-note les résultats avec un cross-encoder quand le re-ranking est activé. Tous portent le préfixe `RAG_` et sont lus par les conteneurs `platform` et `convex` au boot ; après un changement, lance `docker compose restart platform convex` pour qu'il prenne effet. | Nom | Défaut | Description | | ---------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `RAG_RERANKING_ENABLED` | `false` | Re-note les candidats fusionnés BM25 + vecteur avec un cross-encoder avant de renvoyer les résultats. Améliore la précision au prix de la latence par requête. | | `RAG_RERANKING_MODEL` | `cross-encoder/ms-marco-MiniLM-L-6-v2` | Identifiant du modèle cross-encoder transmis au fournisseur de rerank. | | `RAG_RERANKING_PROVIDER` | `local` | Doit être réglé sur `api` pour activer le re-ranking — il poste les candidats à un endpoint `/rerank` externe (compatible Cohere/Jina). `local` n'est plus supporté et échoue tout de suite. | | `RAG_RERANKING_TOP_K` | `10` | Nombre maximal de résultats que le reranker renvoie. La réponse ne dépasse jamais le `top_k` de la requête. | | `RAG_RERANKING_CANDIDATES` | `30` | Taille du pool de candidats fourni au reranker. Un pool plus large améliore la qualité de re-notation et coûte proportionnellement plus de temps par requête. | | `RAG_RERANKING_API_BASE_URL` | non défini | URL de base du fournisseur de rerank ; la plateforme appelle `{base_url}/rerank`. Obligatoire quand le re-ranking est activé. | | `RAG_RERANKING_API_KEY` | non défini | Token Bearer envoyé à l'endpoint de rerank externe. Laisse-le non défini pour les endpoints sans authentification. | Le re-ranking est livré désactivé parce qu'il ajoute de la latence par requête et dépend d'un endpoint externe. Active-le — en réglant `RAG_RERANKING_PROVIDER=api` et en pointant `RAG_RERANKING_API_BASE_URL` vers un service de rerank hébergé — quand la précision du retrieval compte plus que le temps de réponse. Il n'y a aucun modèle en in-process à télécharger ou à mettre en cache ; le re-ranking désactivé, la recherche renvoie le classement hybride BM25 + vecteur simple. ## 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](/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. ## Où cela s'inscrit Les variables ici sont la surface de contact de l'opérateur ; la surface UI qui en consomme la plupart vit sous [Plateforme administration](/fr/platform/admin/overview). Les clés de fournisseur sont la moitié-et-moitié : les clés elles-mêmes vivent dans `providers/*.secrets.json`, mais l'UI sous **Paramètres > Fournisseurs IA** est ainsi que tu les ajoutes et les fais tourner en pratique. La lecture suivante à mettre en file est [Fournisseurs](/fr/self-hosted/configuration/providers) — elle couvre la forme fichier, les modes SOPS et le comportement de résolution et de failover. # Authentification Source: https://tale.dev/docs/fr/self-hosted/configuration/authentication Tale ship quatre modes de sign-in qu'un opérateur choisit par instance. Le défaut est mot de passe local, avec un utilisateur par e-mail ; Microsoft Entra et OIDC générique délèguent l'identité à un fournisseur externe ; trusted headers remet la responsabilité à un reverse proxy qui termine déjà SSO en amont. La décision est permanente au sens où elle façonne comment les utilisateurs sont provisionnés — changer de mode après le rollout est possible, mais chaque utilisateur existant doit être re-mappé sur la nouvelle source d'identité. Mot de passe local et trusted headers se basculent par variables d'env ([Référence des variables d'environnement](/fr/self-hosted/configuration/environment-reference)) ; Microsoft Entra et OIDC générique se configurent par organisation dans l'app en marche. Cette page est le walkthrough mode par mode — quand choisir chacun, ce qu'il change pour l'utilisateur, ce qui casse quand il est mal configuré. ## Mot de passe local (défaut) Mot de passe local est le mode que tu obtiens si tu ne règles rien. La plateforme stocke un hash bcrypt dans Postgres, signe la session avec `BETTER_AUTH_SECRET`, et l'utilisateur se connecte avec un e-mail et un mot de passe que l'admin lui a fourni dans l'invitation. Aucun fournisseur d'identité externe n'est impliqué. Choisis-le sur les petites instances et les déploiements auto-hébergés air-gapped où ajouter un IdP crée plus de friction qu'il n'en résout. Le coût : la réinitialisation de mot de passe passe par l'admin (ou par e-mail si `SMTP_*` est configuré), et il n'y a pas d'histoire SSO. ```bash # .env — pas de flag nécessaire pour le mot de passe local HOST=localhost SITE_URL=https://localhost BETTER_AUTH_SECRET=... ``` ## Microsoft Entra Le mode Microsoft Entra ajoute un bouton **Continuer avec SSO** à l'écran de sign-in et accepte les utilisateurs d'un tenant que tu contrôles. Il n'y a pas d'interrupteur par variable d'env : la connexion se configure par organisation sous **Paramètres > SSO d'entreprise** une fois la plateforme démarrée — choisis le protocole **Microsoft Entra ID** et renseigne le client ID, le client secret et l'URL d'issuer de ton enregistrement d'application. Le walkthrough complet, y compris le mapping des rôles et la synchronisation groupes-vers-équipes, est [SSO d'entreprise et provisionnement](/fr/platform/admin/enterprise-sso). Deux valeurs de déploiement doivent être justes avant que le flow fonctionne : `SITE_URL`, car l'URL de redirection de sign-in en est dérivée, et `BETTER_AUTH_SECRET`, qui signe le state OAuth. L'URI de redirection à enregistrer dans Entra est `${SITE_URL}${BASE_PATH}/http_api/api/sso/callback` — la page de paramètres affiche l'URL exacte à copier, et elle doit correspondre octet pour octet, sinon Entra rejette le sign-in avec `AADSTS50011`. L'ID du tenant dans l'enregistrement d'application Entra restreint qui peut se connecter ; un enregistrement multi-tenant accepte quiconque a un compte Microsoft, ce qui est rarement ce que tu veux. ## OIDC générique L'OIDC générique accepte tout fournisseur d'identité conforme à la spec — Keycloak, Authentik, Okta, Google Workspace. La configuration vit sur la carte **Authentification unique** sous **Paramètres > Intégrations** : choisis le type de fournisseur **OIDC générique**, saisis l'URL de l'émetteur, le client ID et le client secret, et Tale lit les points de terminaison d'autorisation, de jeton et userinfo depuis le document `.well-known/openid-configuration` de l'émetteur. Le flow utilise le grant Authorization Code standard avec PKCE (S256). Tale ne stocke aucun secret sur disque pour OIDC ; le client ID et le client secret vivent dans le credential store chiffré. L'URI de redirection à enregistrer chez ton fournisseur est `${SITE_URL}/http_api/api/sso/callback`. Les fournisseurs d'identité ne s'accordent pas sur l'emplacement des claims, donc la carte te laisse pointer Tale vers les tiens. Les champs **Claim d'e-mail**, **Claim de nom** et **Claim de groupes** prennent un nom de claim ou un chemin en notation pointée dans la réponse userinfo — les rôles de realm de Keycloak, par exemple, vivent sous `realm_access.roles`. Les règles de correspondance des rôles attribuent les rôles de la plateforme au sign-in : une règle **Groupe** compare les groupes de l'utilisateur à un motif avec caractère générique (`platform-admin*` → Admin), une règle **Claim** compare n'importe quel claim résolu par chemin pointé. **Provisionnement automatique des équipes** reflète les groupes renvoyés par ton fournisseur comme équipes Tale à chaque sign-in, moins les groupes que tu exclus. Un exemple Keycloak complet : crée un client confidentiel `tale-platform` avec l'URI de redirection ci-dessus, ajoute un mapper Group Membership pour que le client émette `groups` dans userinfo, puis dans Tale règle l'émetteur sur `https://keycloak.example.com/realms/<realm>`, ajoute une règle de groupe `platform-admin*` → Admin et clique sur **Tester la connexion** — la discovery est validée avant que quoi que ce soit ne soit enregistré. C'est le mode pour les équipes qui font déjà tourner un IdP et veulent leur surface d'identité existante dans Tale. ## Trusted headers Trusted headers est le mode pour les sites qui terminent SSO sur un reverse proxy en amont — oauth2-proxy, Pomerium, Authelia. Le proxy authentifie l'utilisateur et transmet les en-têtes d'identification (`X-Auth-Request-Email`, `X-Auth-Request-Preferred-Username`) ; Tale fait confiance à ces en-têtes et crée ou met à jour l'enregistrement utilisateur à la volée. ```bash # .env TRUSTED_HEADERS_ENABLED=true ``` Le modèle de menace est délicat. Tout ce qui peut joindre le conteneur plateforme avec ces en-têtes devient l'utilisateur qu'ils nomment. Restreins le port plateforme pour que seul le proxy puisse lui parler (un réseau Docker ou une règle firewall hôte), et n'expose jamais le conteneur plateforme directement à Internet quand ce mode est actif. ## Où cela s'inscrit Les quatre modes sont mutuellement exclusifs en esprit mais techniquement additifs — Microsoft Entra et trusted headers peuvent coexister sur la même instance si ton histoire IdP est en pleine migration. La table complète des compromis par mode vit dans [Membres et rôles](/fr/platform/admin/members-and-roles) côté utilisateur ; cette page couvre le commutateur de l'opérateur. La prochaine page de configuration qui vaut la lecture est [Fournisseurs](/fr/self-hosted/configuration/providers) — une fois que les utilisateurs peuvent se connecter, il faut toujours au moins un fournisseur de modèle câblé avant qu'ils ne puissent faire quoi que ce soit. # Fournisseurs Source: https://tale.dev/docs/fr/self-hosted/configuration/providers Tale stocke chaque fournisseur de modèle sous forme de deux fichiers sous `providers/` — un `<name>.json` pour la forme publique (URL de base, modèles, capacités) et un `<name>.secrets.json` pour les clés API. La séparation existe pour que la config soit safe à commit et que les secrets reçoivent le traitement chiffré que SOPS leur donne. Le conteneur `tale-platform` lit les deux au boot et les surveille pour les changements ; redémarrer le conteneur n'est pas requis pour prendre en compte des éditions. La référence est le format de fichier sur disque et l'ordre des opérations à suivre en ajoutant un fournisseur. Le flow piloté par l'UI ("Paramètres > Fournisseurs") s'assied sur les mêmes fichiers ; les deux produisent des résultats identiques. ## Le fichier de config `providers/<name>.json` décrit la forme publique du fournisseur. Le `displayName` apparaît dans l'UI, le tableau `models` nomme tout ce qui est joignable via ce fournisseur, et chaque modèle déclare ses tags (`chat`, `vision`, `embedding`, `transcription`, `text-to-speech`). ```json { "displayName": "OpenRouter", "description": "Chat, vision, embeddings, voix et génération d'images via une seule clé.", "baseUrl": "https://openrouter.ai/api/v1", "secretsEnv": "TALE_PROVIDER_KEY_OPENROUTER", "defaults": { "transcription": "openai/whisper-1", "text-to-speech": "openai/gpt-4o-mini-tts-2025-12-15" }, "models": [ { "id": "openai/whisper-1", "displayName": "Whisper v1", "tags": ["transcription"], "transcriptionMode": "json-base64", "cost": { "centsPerAudioMinute": 0.6 } } ] } ``` L'ensemble complet des champs vit dans [`builtin-configs/providers/`](https://github.com/tale-project/tale/tree/main/builtin-configs/providers). Le défaut livré est un seul `openrouter.json` qui couvre le chat, la vision, les embeddings, la transcription, la synthèse vocale et la génération d'images — une clé pour tout — avec des presets curés pour les fournisseurs courants (Anthropic, OpenAI, Google, xAI, Mistral, Meta, DeepSeek, Qwen, Cohere, Amazon, Perplexity et plus). Pour appeler un fournisseur directement plutôt que via OpenRouter, ajoute un autre fichier (par exemple un `openai.json` pointant vers `https://api.openai.com/v1`) ; voir [Modèles livrés en standard](/fr/platform/models) pour le catalogue complet par défaut. `transcriptionMode` sélectionne la forme du corps de requête d'un modèle `transcription` : `json-base64` (l'enveloppe `input_audio` d'OpenRouter) ou, s'il est omis, `multipart` — l'upload `multipart/form-data` OpenAI/Whisper qu'attendent aussi vLLM, LocalAI et une clé OpenAI directe. Définis-le selon l'endpoint de transcription que tu vises. ### Capacités des modèles et synchronisation auto Chaque modèle peut déclarer des métadonnées optionnelles utilisées par le routage par complexité et l'Adaptive Reasoning Governor : `contextWindow`, `maxOutputTokens`, `qualityScore` (0–1), `tier` (`draft`/`standard`/`frontier`), `routingTags` (domaines préférés), `reasoning` (le bouton de pilotage — `effort` ou `budgetTokens`) et `promptCaching` (`auto-server` ou `explicit-breakpoints`). Tout ce que tu omets est rempli depuis le catalogue OpenRouter à l'exécution ; tout ce que tu définis l'emporte. Mets `"hidden": true` pour retirer un modèle des sélecteurs (composeur de chat, création d'agent) tout en le gardant résoluble pour les agents qui le référencent déjà — la façon de retirer une version remplacée sans casser les workflows existants. Ces champs restent aussi à jour tout seuls : une fois par semaine, Tale fusionne les nouvelles données OpenRouter dans la config fournisseur de chaque organisation — ajoutant les nouvelles versions phares, masquant celles remplacées et actualisant les valeurs de capacités — en ne touchant que les champs que tu n'as pas personnalisés. Désactive-le par organisation avec l'interrupteur **Synchronisation auto hebdomadaire** sur la carte du catalogue de modèles dans **Paramètres > Fournisseurs**. Quand `maxOutputTokens` n'est pas défini, Tale plafonne la sortie à **32 768** tokens. Mets `0` pour n'envoyer aucune limite. Réduis la valeur au plafond réel de ton déploiement si le fournisseur rejette les valeurs trop élevées (par ex. un déploiement Azure GPT-4o renvoyant `max_tokens is too large`). ### Mappage du corps de requête Certains points de terminaison attendent une forme de requête légèrement différente de la forme OpenAI-compatible standard. Un modèle — ou le fournisseur, comme valeur par défaut — peut déclarer un `requestBodyMap` qui réécrit le corps de requête final à l'envoi : ```json { "requestBodyMap": { "rename": { "max_tokens": "max_completion_tokens" }, "remove": ["frequency_penalty"] } } ``` `rename` renomme un champ en un autre (appliqué en premier) ; `remove` supprime les champs que le point de terminaison rejette. Un `requestBodyMap` par modèle l'emporte sur celui au niveau du fournisseur en cas de clés en conflit. Contrairement à `providerOptions`, ces instructions n'atteignent jamais le fournisseur — elles réécrivent le corps sur place, ce qui en fait la manière prise en charge de modifier un champ réservé comme `max_tokens`. Le cas classique est un déploiement de **raisonnement** OpenAI / Azure (série o, GPT-5), qui rejette `max_tokens` et exige `max_completion_tokens`. Si tu marques le modèle comme modèle de raisonnement (en réglant son bouton `reasoning`), Tale applique ce renommage automatiquement — tu n'as alors besoin de `requestBodyMap` que pour d'autres particularités de point de terminaison. ## Le fichier de secrets `providers/<name>.secrets.json` est un objet JSON plat avec la clé API sous le nom de champ que le fournisseur attend : ```json { "apiKey": "sk-..." } ``` Avec `SOPS_AGE_KEY` ou `SOPS_AGE_KEY_FILE` défini, ce fichier est stocké chiffré sur disque. Avec les deux non définis, il est en clair au mode 0600 — n'atteins ce mode que sur des disques chiffrés au repos. Le walkthrough de chiffrement complet vit dans [Secrets avec SOPS](/fr/self-hosted/configuration/secrets-with-sops). ## Source de clé par variable d'environnement {#environment-variable-key-source} Si tes secrets vivent déjà dans Kubernetes Secrets, Vault ou un gestionnaire de secrets cloud, tu peux pointer un fournisseur sur une **variable d'environnement** plutôt que sur un fichier de secrets. Ajoute un `secretsEnv` au fichier de config (il nomme la variable ; le nom lui-même n'est pas un secret, il reste donc dans la config committable) : ```json { "displayName": "OpenRouter", "baseUrl": "https://openrouter.ai/api/v1", "secretsEnv": "TALE_PROVIDER_KEY_OPENROUTER", "models": [ { "id": "openai/gpt-4o", "displayName": "GPT-4o", "tags": ["chat", "vision"], "secretsEnv": "TALE_PROVIDER_KEY_OPENAI_DIRECT" } ] } ``` Deux garde-fous s'appliquent : - **Préfixe réservé (obligatoire).** Le nom de la variable doit commencer par `TALE_PROVIDER_KEY_` (par ex. `TALE_PROVIDER_KEY_OPENROUTER`). Tout autre nom est rejeté, donc une config qui nomme une variable sans préfixe se résout à aucune clé. Cela empêche un acteur qui écrit la config de pointer `secretsEnv` sur un secret de déploiement étranger (par ex. `SOPS_AGE_KEY`) et de le faire envoyer à une URL de fournisseur. La barrière de préfixe est codée en dur — il n'y a aucun commutateur de déploiement à définir. - **Longueur.** Le nom doit faire 40 caractères ou moins — la plateforme synchronise les variables d'environnement vers son backend Convex, qui plafonne les noms de variables à 40. Ordre de résolution, le plus haut d'abord : `secretsEnv` au niveau modèle → `secretsEnv` au niveau fournisseur → le fichier de secrets (`modelKeys[id]` puis `apiKey`). Chaque palier est sauté quand il ne donne rien, donc une variable configurée mais vide retombe sur le fichier. Les valeurs d'env sont trimmées (un retour à la ligne en queue venant d'un secret monté est une cause fréquente de `401`). Contrairement au **fichier** de secrets — que le watcher relit à chaque requête — une **valeur** de variable d'environnement est lue une seule fois au démarrage du processus. La changer demande de **redémarrer le conteneur `tale-platform`** (il resynchronise l'env vers Convex au boot). La plateforme synchronise automatiquement la variable vers le backend Convex, donc les actions RAG et crawler en in-process la récupèrent depuis la même synchronisation — il n'y a pas de service séparé à recréer. ## Ajouter un fournisseur L'ordre compte — le watcher lit le fichier de config d'abord pour savoir que le fournisseur existe, puis résout le secret à la première requête. 1. Dépose le fichier de config à `providers/<name>.json`. 2. Dépose le fichier de secrets à `providers/<name>.secrets.json` (chiffré ou en clair selon ton mode SOPS). 3. Rafraîchis **Paramètres > Fournisseurs** dans l'UI — le nouveau fournisseur apparaît en quelques secondes (le watcher poll toutes les 2 s). 4. Choisis le modèle par défaut du nouveau fournisseur sous **Paramètres > Modèles** pour que les agents qui résolvent "default" y atterrissent. Si le fichier de config est malformé, la plateforme log un avertissement et saute le fournisseur ; le reste reste joignable. ## Échanger une clé Édite le fichier de secrets en place — le watcher prend le changement et la prochaine requête à ce fournisseur utilise la nouvelle clé. Les requêtes en vol existantes tiennent encore l'ancienne clé ; annule et réessaie pour forcer la re-résolution. (Les clés issues d'une [variable d'environnement](#environment-variable-key-source) sont l'exception : changer la valeur demande un redémarrage du conteneur, pas seulement une édition de fichier.) ## Désactiver un fournisseur Soit supprime les deux fichiers, soit mets `"disabled": true` au niveau racine de la config. Désactiver garde le fichier sur disque pour plus tard (pratique quand tu veux garder la liste des modèles mais arrêter la facturation) ; supprimer l'enlève entièrement. Les agents qui ont nommé le fournisseur explicitement commencent à échouer à la prochaine requête — bascule-les sur un fallback d'abord. ## Où cela s'inscrit Les fournisseurs sont le seul demi-et-demi entre config serveur (cette page) et UI (l'écran **Fournisseurs**). Les clés elles-mêmes vivent dans `providers/*.secrets.json` ; la gestion SOPS vit dans [Secrets avec SOPS](/fr/self-hosted/configuration/secrets-with-sops). Les défauts au niveau modèle, contre lesquels les agents résolvent, sont documentés sous [Plateforme > Modèles](/fr/platform/models). # Rétention Source: https://tale.dev/docs/fr/self-hosted/configuration/retention La rétention dans Tale est la policy qui supprime les vieilles données sur un planning — chats, documents, audit logs, exécutions de workflow, lignes du ledger d'usage de tokens. L'opérateur fixe les bornes (minimums et maximums) par catégorie ; l'admin de chaque organisation choisit la fenêtre de rétention réelle dans ces bornes via **Paramètres > Gouvernance > Politique de rétention**. La séparation existe pour qu'une équipe d'hébergement puisse imposer des planchers de compliance sans micromanager chaque tenant. Cette page couvre la surface opérateur. Les contrôles côté admin et les descriptions par catégorie vivent dans [Gouvernance > Politique de rétention](/fr/platform/admin/governance/policies-and-limits). ## Comment marchent les bornes Chaque catégorie de rétention — fils de chat, documents, clients, fournisseurs, templates de prompt, lignes de ledger, audit logs, exécutions de workflow, logs de triggers de workflow, tentatives de login — a un `min` et un `max`. Un admin d'org fixe une valeur dans cette fenêtre. Resserrer le plancher sur une instance existante est un flow en plusieurs étapes : l'opérateur propose la nouvelle borne, chaque admin affecté voit une bannière, le changement s'applique une fois accepté. | Catégorie | Plancher typique | Pourquoi | | ---------------------------- | ---------------- | --------------------------------------------------------- | | Historique de chat | 30 j | La plupart veulent du contexte récent, pas pour toujours | | Documents | 1 a | Les connaissances vieillissent lentement | | Audit logs | 1 a minimum | Les frameworks de compliance attendent un an | | Ledger d'usage de tokens | 90 j | Analytics et rapports de budget s'appuient sur les lignes | | Logs d'exécution de workflow | 30 j | Le debugging remonte rarement plus loin | | Tentatives de login | 30 j | L'enquête brute-force a besoin de la trace d'audit | Les défauts livrés sont lâches ; resserre selon ta posture de compliance. ## Où tu fixes les bornes Sous la disposition org-first, les bornes de rétention sont **par org** : édite `retention.json` directement dans le sous-arbre d'une org sous `TALE_CONFIG_DIR` (par défaut `/app/data/` dans le conteneur plateforme, le fichier se trouve donc à `/app/data/<org>/retention.json`, p. ex. `/app/data/default/retention.json`). Chaque org a son propre fichier ; celui de l'org `default` est le modèle qu'un nouveau déploiement reprend au premier démarrage. ```json { "chatHistory": { "min": 30, "max": 730, "unit": "days" }, "documents": { "min": 1, "max": 3650, "unit": "days" }, "auditLog": { "min": 365, "max": 3650, "unit": "days" }, "tokenLedger": { "min": 90, "max": 1095, "unit": "days" } } ``` Le conteneur plateforme surveille le fichier ; les changements proposent une mise à jour de bornes pour chaque org existante. Les admins voient la proposition dans leur écran **Politique de rétention** et l'appliquent eux-mêmes. L'étape propose-puis-applique est délibérée : resserrer un plancher raccourcit l'historique, ce qui est une action destructive qu'aucun opérateur ne devrait poser silencieusement sur chaque tenant. Les fenêtres de rétention choisies par l'admin vivent dans un fichier distinct, `retention-policy.json`, à côté des bornes dans le même dossier `governance/`. Il contient des champs plats `<catégorie>Enabled` / `<catégorie>RetentionDays` (p. ex. `"auditLogEnabled": true, "auditLogRetentionDays": 730`), pas les bornes `min`/`max`. Ce fichier est écrit par **Paramètres > Gouvernance > Politique de rétention** dans l'app, donc les admins ne l'éditent normalement jamais à la main — garde-le distinct du fichier de bornes géré par l'opérateur. ## Le sweep de rétention Un cron planifié dans `tale-convex` fait la suppression réelle. Chaque catégorie est sweepée indépendamment — un run lent sur une ne bloque pas les autres. Les suppressions sont auditées (chaque catégorie a son propre événement `*.retention_deleted`), et restaurer une entité dans sa fenêtre de grâce est possible depuis **Corbeille** avant le sweep final. Les entrées d'audit log sont elles-mêmes soumises à la rétention, mais leur plancher est imposé par déploiement, pas par org : la rétention d'audit log la plus stricte (la plus courte) à travers toutes les orgs est ce qui tourne effectivement. Un tenant plus strict tire tout le monde plus serré — garde ça en tête sur les instances multi-tenants. ## Legal hold Un legal hold gèle la rétention pour un scope spécifique : un fil unique, un enregistrement client, ou toute une organisation. Les entités tenues sautent le sweep jusqu'à ce que le hold soit relâché. Le hold lui-même est audité ; les holds à l'échelle de l'org sont assez bruyants pour que l'UI fasse remonter une confirmation avant qu'ils s'appliquent. ## Où cela s'inscrit Le fichier de bornes est le levier de l'opérateur ; les fenêtres par catégorie que l'admin voit sont documentées dans [Politique de rétention](/fr/platform/admin/governance/policies-and-limits). Si tu fixes des bornes contre un framework de compliance (RGPD, HIPAA, SOC 2), le plancher d'audit log est habituellement ce que les auditeurs vérifient en premier. # Configuration de l'observabilité Source: https://tale.dev/docs/fr/self-hosted/configuration/observability-config Tale ship trois coutures d'observabilité : logs stdout depuis chaque conteneur, métriques au format Prometheus derrière un bearer token, et reporting d'erreurs Sentry optionnel. Les défauts sont assez bruyants pour repérer un crash et assez discrets pour tenir dans le journald d'un seul hôte ; les boutons de production ci-dessous ajoutent les chemins structurés que ta stack de monitoring existante peut scraper. Aucune des trois n'envoie quoi que ce soit hors-hôte sauf si tu le configures. Cette page couvre les interrupteurs côté serveur. Le playbook d'alerte côté opérateur vit dans [Opérations](/fr/self-hosted/operate/observability/operations), et la recherche par symptôme dans [Dépannage](/fr/self-hosted/operate/observability/troubleshooting). ## Logs Chaque conteneur écrit des logs JSON structurés ou console vers stdout, capturés par le driver `json-file` par défaut de Docker avec une rotation de 10 Mo par fichier et 3 fichiers. La destination des logs est fonction de comment tu déploies : - Hôte unique avec journald — `journalctl -u docker` porte le tout. - Hôte unique sans journald — `docker compose logs -f <service>` pour le tailing en direct. - Aggregator (Loki, Vector, Fluent Bit) — pointe le driver de logging Docker dessus via `daemon.json`. Tale ne ship pas de log shipper. L'échange de driver est le point d'intégration supporté. ## Métriques Le proxy Caddy expose trois chemins de métriques derrière un seul bearer token : | Chemin | Source | Ce qui est dedans | | -------------------- | --------------- | ------------------------------------------------------------------------------------------------------- | | `/metrics/platform` | `tale-platform` | Latence HTTP, compteurs de routes, métriques de processus Node, gauges de cible SLA de temps de réponse | | `/metrics/convex` | `tale-convex` | 261 métriques Convex intégrées, plus les timings RAG et de crawl | | `/metrics/sla-rules` | `tale-platform` | Rules Prometheus de recording + alerting générées pour les SLA de temps de réponse | Le travail de connaissances (recherche RAG, ingestion de documents, crawling web) tourne désormais dans le backend Convex, donc ses timings empruntent la série `/metrics/convex` plutôt qu'un endpoint séparé. Mets `METRICS_BEARER_TOKEN` dans `.env` pour activer ces endpoints ; laisse-le non défini pour qu'ils retournent 401 à chaque requête. Le chemin `/metrics/sla-rules` est un fichier YAML de rules en lecture seule que tu charges dans Prometheus, pas une cible de scrape — les seuils qu'il porte sont documentés dans [Opérations](/fr/self-hosted/operate/observability/operations). Tout sauf les chemins listés retourne aussi 401, donc un scraper mal routé ne voit pas accidentellement les endpoints de santé internes de la plateforme. Une stanza de scrape Prometheus qui marche : ```yaml scrape_configs: - job_name: tale-platform scheme: https metrics_path: /metrics/platform authorization: credentials: <METRICS_BEARER_TOKEN> static_configs: - targets: ['tale.example.com'] ``` Duplique la stanza par chemin, ou utilise un job unique avec `relabel_configs` si tu préfères. ## Suivi d'erreurs avec Sentry Sentry est opt-in via `SENTRY_DSN`. GlitchTip et Bugsink auto-hébergés marchent aussi, puisqu'ils parlent le même format de DSN. Les conteneurs plateforme et convex lisent tous les deux le DSN et taguent les événements avec le nom du conteneur. ```bash # .env SENTRY_DSN=https://your-key@your-sentry-host/project-id SENTRY_TRACES_SAMPLE_RATE=0.1 ``` Le sample rate plafonne les traces de performance ; laisse-le non défini pour le défaut 1.0 en développement et resserre-le (0.05–0.2) en production. Les stack frames sont envoyés sans rédaction, donc pointe le DSN sur une infra que tu contrôles si tes payloads d'erreur sont sensibles. ## Ce qui ne ship pas encore Les traces OpenTelemetry ne sont pas intégrées aux conteneurs. Les données sont joignables indirectement — les durées d'action Convex et les timings de routes HTTP arrivent par les métriques Prometheus — mais il n'y a pas d'exportateur OTLP sur la boîte aujourd'hui. Si tu as besoin d'export de traces complet, fais tourner un OpenTelemetry Collector à côté de Tale et scrape les endpoints Prometheus depuis lui. ## Où cela s'inscrit Les trois coutures ci-dessus sont les points de contact avec le reste de ta stack de monitoring ; les seuils d'alerte et la checklist d'astreinte vivent dans [Opérations](/fr/self-hosted/operate/observability/operations). Si quelque chose brûle là, maintenant, et qu'il te faut l'index par symptôme, saute à [Dépannage](/fr/self-hosted/operate/observability/troubleshooting). # Secrets avec SOPS Source: https://tale.dev/docs/fr/self-hosted/configuration/secrets-with-sops Tale stocke les clés API des fournisseurs dans des fichiers `providers/*.secrets.json` sur disque. Le mode par défaut après `tale init` chiffre ces fichiers avec SOPS en utilisant une clé age ; un mode alternatif lit plusieurs clés depuis un fichier (le chemin de rotation) ; un troisième mode garde les fichiers en clair au mode 0600 pour les environnements où le disque est chiffré au repos et où la rotation est gérée en externe. Cette page est le walkthrough opérateur des trois modes et du chemin de rotation sûr. Les variables d'env qui pilotent les modes sont `SOPS_AGE_KEY` et `SOPS_AGE_KEY_FILE` — leurs lignes de référence vivent dans [Référence des variables d'environnement](/fr/self-hosted/configuration/environment-reference#provider-secrets-encryption). Cette page est la version plus longue. ## Les trois modes | Mode | Variables d'env | Quand utiliser | | --------------- | ---------------------------------- | ----------------------------------------------------------------- | | Clé age inline | `SOPS_AGE_KEY=AGE-SECRET-KEY-1...` | Défaut après `tale init`. Hôte unique, clé unique. | | Fichier de clés | `SOPS_AGE_KEY_FILE=/path/to/keys` | Requis pour la rotation. Une clé age par ligne, commentaires `#`. | | Clair à 0600 | Les deux non définis | Disque chiffré au repos, ou outillage externe écrit les fichiers. | Le conteneur plateforme choisit le mode au boot. La forme inline est la plus simple ; la forme fichier est la seule qui supporte plusieurs lecteurs (ce qui rend la rotation possible sans downtime) ; la forme en clair saute SOPS entièrement et fait confiance au système de fichiers. ## Mode chiffré au premier boot `tale init` génère une paire de clés age et écrit la moitié privée dans `SOPS_AGE_KEY` de ton `.env`. Les fichiers de secret de fournisseur écrits via **Paramètres > Fournisseurs** sont chiffrés à la sauvegarde : ```bash # Inspecte — le fichier est du JSON SOPS-chiffré, pas la clé API en clair cat providers/openai.secrets.json # { # "apiKey": "ENC[AES256_GCM,data:...,iv:...,tag:...]", # "sops": { ... } # } ``` Le déchiffrement se passe in-process quand le conteneur plateforme lit le fichier. La clé age ne quitte jamais la mémoire du conteneur plateforme. ## Faire tourner la clé age La rotation est le seul chemin que la forme inline ne couvre pas — seul `SOPS_AGE_KEY_FILE` te laisse accepter du ciphertext lisible par l'ancienne et la nouvelle clé pendant le cutover. Le walk : ```bash # 1. Génère une nouvelle clé age age-keygen -o /etc/tale/age-keys.txt # 2. Ajoute la nouvelle clé comme deuxième ligne dans le fichier echo "AGE-SECRET-KEY-1NEW..." >> /etc/tale/age-keys.txt # 3. Pointe .env sur le fichier et redémarre le conteneur plateforme sed -i 's|^SOPS_AGE_KEY=.*|# SOPS_AGE_KEY=|' .env sed -i 's|^# SOPS_AGE_KEY_FILE=.*|SOPS_AGE_KEY_FILE=/etc/tale/age-keys.txt|' .env docker compose restart tale-platform tale-convex ``` Maintenant l'ancienne et la nouvelle clé peuvent déchiffrer les fichiers existants. Re-sauvegarde la clé API de chaque fournisseur sous **Paramètres > Fournisseurs** — chaque sauvegarde produit du ciphertext lisible par les deux clés. Une fois que chaque fournisseur a été re-sauvegardé (la colonne **Dernière rotation** dans le tableau des fournisseurs te dit lesquels tiennent encore l'ancien ciphertext), retire l'ancienne clé du fichier : ```bash # 4. Drop la ligne de l'ancienne clé et redémarre à nouveau sed -i '/^AGE-SECRET-KEY-1OLD/d' /etc/tale/age-keys.txt docker compose restart tale-platform tale-convex ``` L'ordre est porteur : ne retire jamais l'ancienne clé avant que chaque fichier soit re-chiffré, sinon le conteneur plateforme échouera à lire les fichiers encore-anciens au prochain déchiffrement. ## Basculer en clair Quand le disque hôte est chiffré au repos (LUKS, chiffrement AWS EBS, GCP CSEK) et que tu ne veux pas d'une deuxième couche de gestion de clés, le mode en clair est l'option supportée. Commente `SOPS_AGE_KEY` et `SOPS_AGE_KEY_FILE`, redémarre et re-sauvegarde chaque fournisseur — les fichiers sont maintenant du JSON au mode 0600. Le modèle de risque change : un dump de système de fichiers leaké est maintenant un dump de credentials leaké. Choisis ce mode seulement quand le chiffrement de disque est réel (pas une case à cocher) et audite l'histoire de backup de l'hôte pour confirmer qu'aucun snapshot en clair n'échappe. ## Stores de secret externes Quand tes clés vivent déjà dans Vault, un gestionnaire de secrets cloud ou Kubernetes Secrets, le pattern de première classe est la source de clé par variable d'environnement : pointe chaque fournisseur sur une **variable d'environnement** avec `secretsEnv` et laisse ton store de secrets remplir cette variable. Aucun fichier en clair ne touche le disque, et la barrière de préfixe empêche un acteur qui écrit la config de lire un secret de déploiement étranger. Le mécanisme complet — la barrière de préfixe `TALE_PROVIDER_KEY_`, l'ordre de résolution et le comportement de redémarrage au changement — vit dans [Fournisseurs](/fr/self-hosted/configuration/providers#environment-variable-key-source). L'approche par mount de fichier est l'alternative legacy : écris les fichiers `*.secrets.json` en clair depuis le store externe et fais tourner Tale en mode clair. Cela fonctionne toujours, mais pose la clé en clair sur le disque et casse si tu sauvegardes un fournisseur via l'UI — l'UI écrase le mount. Préfère la source par variable d'environnement, sauf si une contrainte impose la forme fichier. ## Où cela s'inscrit Cette page est le guide opérateur complet de la couche SOPS ; les lignes de référence de variables d'env sont dans [Référence des variables d'environnement](/fr/self-hosted/configuration/environment-reference#provider-secrets-encryption), et le format des fichiers fournisseur lui-même dans [Fournisseurs](/fr/self-hosted/configuration/providers). Si une clé est leakée, la rotation est le même walk ci-dessus exécuté en urgence. # Démarrage rapide auto-hébergé Source: https://tale.dev/docs/fr/self-hosted/install/quickstart C’est le chemin le plus rapide vers un Tale qui tourne : installe la CLI `tale`, puis deux commandes. Le résultat est ta propre organisation sur ta propre machine, joignable dans le navigateur. C’est pensé pour un laptop ou un hôte unique sur lequel essayer Tale ; quand tu veux le faire tourner pour de vrai, le parcours [serveur Linux](/fr/self-hosted/install/linux-server) couvre une installation de production durcie. ## Avant de commencer Il ne te faut rien pour démarrer, et une chose avant qu’un agent puisse répondre : - **Docker** — mais la CLI le provisionne pour toi : s’il manque, `tale dev` propose de l’installer ou de le démarrer avant toute autre chose. Si tu fais déjà tourner [Docker Desktop](https://www.docker.com/products/docker-desktop) (v24+), ou Docker Engine plus le plugin Compose sous Linux, la CLI s’en sert. - Une **[clé API OpenRouter](https://openrouter.ai)** (ou n’importe quel fournisseur compatible OpenAI) pour que les agents aient un modèle à qui parler. Tu n’en as pas besoin pour `tale init` — tu l’ajoutes dans l’app après l’inscription, dans l’assistant de configuration ou sous **Paramètres > Fournisseurs IA**, et tu peux changer de fournisseur plus tard. ## De zéro à connecté <Steps> <Step title="Installe la CLI"> L’installateur détecte ton OS, dépose le binaire `tale` sur ton `PATH`, et c’est la seule étape qui touche ton système — il demande `sudo` quand le répertoire d’installation (par défaut `/usr/local/bin`) n’est pas accessible en écriture. <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> <Check> `tale --version` qui imprime un numéro de version confirme que le binaire a atterri sur ton `PATH`. </Check> </Step> <Step title="Crée un projet"> ```bash tale init my-project cd my-project ``` `tale init` échafaude un répertoire de projet, génère chaque secret de sécurité et écrit le `.env`, de sorte qu’il n’y a rien à éditer à la main. Les valeurs par défaut sont localhost et un certificat auto-signé ; le domaine de production se choisit plus tard, à `tale deploy`. La seule question qu’il pose est de savoir si les agents peuvent lancer `docker` / `docker compose` dans leurs sandboxes — le défaut est non, car l’activer fait tourner un Docker interne privilégié ; une installation mono-utilisateur peut dire oui, un opérateur multi-tenant installe plutôt Sysbox. Il ne demande pas de clé API ; celle-ci est collectée dans l’app une fois que tu es connecté. Il dépose aussi des agents, workflows, intégrations, fournisseurs, skills et branding d’exemple sous `default/`, et écrit `AGENTS.md` (plus un pointeur `CLAUDE.md`) afin qu’un éditeur IA puisse construire des configurations en pleine connaissance du schéma. L’essentiel de cette arborescence est un catalogue, pas une configuration active : sur une nouvelle organisation, seules les entrées marquées `autoInstall` sont actives — le `default/README.md` généré explique la différence. </Step> <Step title="Démarre Tale"> ```bash tale dev ``` Si Docker manque, `tale dev` propose d’abord de l’installer ou de le démarrer. Le premier passage récupère ensuite plusieurs gigaoctets d’images et construit le graphe de conteneurs — la CLI affiche la progression du pull image par image et continue d’attendre ; sur un réseau lent, ça peut prendre des dizaines de minutes. Dès que la stack se signale prête (`Tale is running — open https://localhost`), `tale dev` ouvre ton navigateur automatiquement. S’il ne peut pas, il imprime l’URL à visiter. <Note> Ton navigateur affiche un avertissement de certificat pour le certificat local auto-signé. C’est attendu — accepte-le pour continuer. </Note> Ta configuration sous `default/` est montée dans l’instance en marche, donc les modifications d’agents, de workflows et d’intégrations rechargent à chaud. Arrête la stack avec `Ctrl-C` (ou `tale dev --detach` pour la laisser tourner en arrière-plan). </Step> <Step title="Crée ton compte"> Sur une instance vide, il n’y a pas de page d’inscription à chercher : la première visite atterrit dans l’assistant de configuration unique, qui crée ton compte, te connecte, fait de toi le **Propriétaire** et nomme ton **Organisation**. Tu atterris dans le dashboard — aucune clé admin en jeu, et rien à verrouiller ensuite, car tous ceux qui te suivent arrivent par invitation. <Note> [Premier admin](/fr/self-hosted/install/first-admin) couvre l’assistant en détail, comment les coéquipiers arrivent, et la clé admin du tableau de bord Convex — un outil d’inspection du backend qui ne joue aucun rôle dans la connexion. </Note> </Step> <Step title="Ajoute un modèle et publie un agent"> Tu as maintenant une organisation vide. Deux gestes t’amènent à quelque chose d’utile : ajoute ta clé OpenRouter — l’assistant de configuration la demande juste après la création du compte propriétaire, et **Paramètres > Fournisseurs IA** la prend à tout moment — puis publie ton premier agent avec [Créer un agent](/fr/platform/agents/create). Une confirmation sur la ligne du fournisseur signifie que la clé fonctionne. <Check> Un nouveau chat qui répond à un message est la preuve de bout en bout : fournisseur, modèle et agent fonctionnent tous. À partir d’ici, la doc [Plateforme](/fr/platform) est la référence canonique de chaque fonctionnalité, identique à Cloud. </Check> </Step> </Steps> ## Plutôt du Docker Compose brut ? La CLI enveloppe `docker compose` pour que tu n’aies pas à le faire. Si tu préfères faire tourner la stack depuis un clone du dépôt et gérer Compose toi-même — pour la transparence, des builds air-gapped ou ta propre automatisation — clone le dépôt, copie `.env.example` vers `.env`, règle `HOST` et `SITE_URL`, génère les secrets et lance `docker compose up -d`. Le parcours [serveur Linux](/fr/self-hosted/install/linux-server) et la [référence Docker Compose](/fr/self-hosted/install/docker-compose-reference) couvrent ce chemin de bout en bout. ## Dépannage - **`tale` introuvable après l’installation.** L’installateur nomme le répertoire de destination dans sa sortie ; assure-toi que ce répertoire est sur ton `PATH` (sous Linux, c’est généralement `/usr/local/bin`). - **`tale dev` se termine sur un conflit de port.** Lis l’erreur compose pour voir quel port est pris. Si c’est 443, un autre service lie HTTPS sur l’hôte — libère-le, ou déplace Tale avec `tale dev --port 8443` (l’option ne déplace que le port HTTPS). Le spawner de sandbox lie toujours `127.0.0.1:8003` et ne peut pas être déplacé ; deux projets Tale en dev ne peuvent donc pas tourner en même temps sur une machine. - **Docker ne tourne pas.** `tale dev` propose de le démarrer (ou de l’installer) — accepte l’invite, ou démarre Docker Desktop toi-même (`sudo systemctl start docker` sous Linux) et réessaie. - **Un conteneur crash-loope au premier démarrage.** Presque toujours un secret manquant — relance `tale dev`, qui relance la configuration d’environnement, ou inspecte les logs avec `tale logs platform`. ## Où ça s’utilise Tu as maintenant une instance Tale qui fonctionne sur ta machine. Pour la faire tourner pour de vrai, le parcours [serveur Linux](/fr/self-hosted/install/linux-server) couvre TLS, pare-feu, un utilisateur non-root et les crochets opérationnels que tu veux avant que le vrai trafic n’arrive ; [Installer la CLI tale](/fr/self-hosted/install/cli-install) prépare la CLI à déployer et mettre à jour une instance distante depuis ta machine de travail. # Installation Source: https://tale.dev/docs/fr/self-hosted/install Installer Tale prend trois formes, et la bonne dépend de ce que tu fais du résultat. Cette page t'aiguille vers le chemin qui convient — un essai local rapide, une installation de production derrière TLS, ou la référence Compose brute quand tu veux posséder chaque bouton — pour que tu ne te lances pas dans un parcours de durcissement alors que tu voulais juste cliquer un peu. Les trois chemins atterrissent sur le même produit ; la différence est la part de la stack que tu exploites et la durabilité dont le résultat a besoin. La CLI enveloppe Docker Compose pour les deux premiers, de sorte qu'il n'y a rien à éditer à la main, tandis que le chemin de la référence est pour les équipes qui font tourner Compose elles-mêmes. ## Essayer Tale sur un laptop Si tu veux une instance qui tourne pour cliquer dedans — sur ta propre machine, sans domaine ni durcissement — le [démarrage rapide](/fr/self-hosted/install/quickstart) est le chemin. Installe la CLI, lance `tale init` puis `tale dev`, et tu es connecté à ta propre organisation en quelques minutes. La CLI provisionne Docker s'il manque, génère chaque secret et monte ta configuration de sorte que les édits rechargent à chaud. C'est le bon chemin pour une évaluation, une démo, ou du développement local contre une vraie stack. Quand tu dépasses le laptop et veux le même projet sur un vrai hôte, le projet d'essai se reporte — `tale deploy` l'amène sur un domaine sans réinitialiser. ## Faire tourner Tale en production Quand du vrai trafic atterrira sur l'instance, le parcours [Linux serveur](/fr/self-hosted/install/linux-server) est le chemin. Il couvre TLS, un pare-feu, un utilisateur non-root, le reverse proxy et les crochets opérationnels que tu veux avant de pointer un domaine dessus. La CLI fait toujours le gros du travail — `tale deploy` exécute un déploiement blue-green sans interruption avec health checks et rollback — mais ce parcours ajoute la configuration au niveau de l'hôte qu'un essai saute. Après le premier déploiement, [Premier admin](/fr/self-hosted/install/first-admin) explique l'assistant de configuration unique qui fait du premier compte l'**Owner** — tous les suivants arrivent par invitation, donc il n'y a pas d'inscription ouverte à fermer — et [Installation de la CLI](/fr/self-hosted/install/cli-install) configure la CLI sur une workstation pour déployer et mettre à jour une instance distante. ## Posséder la couche Compose Si tu préfères faire tourner la stack depuis un clone du dépôt et gérer Compose toi-même — pour la transparence, des builds air-gapped ou ta propre automation — la [référence Docker Compose](/fr/self-hosted/install/docker-compose-reference) est le chemin. Elle documente le fichier de base et les overlays que la CLI génère en coulisse, pour que tu puisses les reproduire ou les étendre à la main. C'est le plus de contrôle et le plus de travail ; la plupart des équipes sont mieux servies par les chemins CLI ci-dessus. Ce chemin se marie au parcours [Linux serveur](/fr/self-hosted/install/linux-server) pour les pièces au niveau de l'hôte (TLS, pare-feu, utilisateur) que Compose seul ne couvre pas. ## Où cela s'inscrit Les trois chemins d'installation échangent la commodité contre le contrôle : le [démarrage rapide](/fr/self-hosted/install/quickstart) est le moyen le plus rapide vers une instance qui tourne, le parcours [Linux serveur](/fr/self-hosted/install/linux-server) la durcit pour du vrai trafic, et la [référence Docker Compose](/fr/self-hosted/install/docker-compose-reference) te remet chaque bouton quand les valeurs par défaut de la CLI ne suffisent pas. Choisis selon la durabilité : un essai que tu jetteras veut le démarrage rapide ; une instance dont ton équipe dépend veut le parcours de production. Une fois installé, les pages [Configuration](/fr/self-hosted/configuration/environment-reference) sont la source de vérité pour chaque variable d'environnement et fichier de fournisseur, et la section [Exploiter](/fr/self-hosted/operate/container-architecture) couvre les mises à jour, les sauvegardes et l'observabilité de la stack en marche. # Référence Docker Compose Source: https://tale.dev/docs/fr/self-hosted/install/docker-compose-reference Tale livre une poignée de fichiers Docker Compose. La base est `compose.yml` ; le reste, ce sont des overlays qui ajoutent ou remplacent des services pour des scénarios précis — développement, docs, test. Cette page nomme chaque fichier, dit quand le choisir, et donne la règle de superposition à laquelle tout le reste obéit. La forme est volontairement conservatrice. Le fichier de base tout seul tourne en production ; chaque overlay est opt-in via `-f` et n'ajoute que ce qu'il doit. Mémorise la base et un seul overlay, pas toute la grille. ## Un compose-up déroulé Une instance de production sur un seul hôte tourne depuis la base seule : ```bash docker compose up -d ``` Un développeur qui hacke sur platform et docs en même temps superpose deux overlays : ```bash docker compose -f compose.yml -f compose.dev.yml -f compose.docs.yml up -d ``` Le fichier le plus à gauche est la base ; chaque fichier suivant fusionne ses clés par-dessus. Les conflits (même service, même clé) se résolvent dernier-fichier-gagne. Le graphe fusionné est ce que Docker démarre. ## Les fichiers compose | Fichier | Cas d'usage | Overrides notables | | ----------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------- | | `compose.yml` | Production sur un seul hôte | La base — chaque service, healthchecks, politique de redémarrage | | `compose.dev.yml` | Développement local avec hot-reload | Monte les sources dans les conteneurs, bascule sur les images dev, expose des ports dev | | `compose.docs.yml` | Ajoute le service du site de docs | Démarre `tale-docs` et route `/docs` à travers le proxy | | `compose.web.yml` | Ajoute le service du site marketing | Démarre `tale-web` et route `/` (racine) à travers le proxy | | `compose.test.yml` | Lance la suite de tests platform contre la pile | Remplace l'image platform par la variante de forme test | | `compose.web.test.yml` | Lance les tests web | Comme `web.yml`, mais la variante de forme test | | `compose.docs.test.yml` | Lance les tests docs | Comme `docs.yml`, mais la variante de forme test | | `compose.test.mock.yml` | Tests d'intégration adossés à des mocks | Remplace les fournisseurs par des implémentations mock | ## Services et leurs rôles Le graphe de base démarre huit conteneurs : - `tale-proxy` — Caddy. TLS, reverse-proxy, redirections 301. - `tale-platform` — l'app TanStack Start. L'UI et l'API côté utilisateur. - `tale-convex` — le backend Convex. WebSocket, queries, mutations, actions — et la recherche RAG, l'ingestion de documents, le crawling web et la génération de documents en in-process, qui étaient autrefois des services séparés. - `tale-db` — Postgres opérationnel (ParadeDB). Le stockage persistant du backend Convex. - `tale-knowledge-db` — Postgres du corpus de connaissances (ParadeDB). La base `tale_knowledge` qui détient les fragments de documents, les embeddings et les pages crawlées, sur le port 5433 pour ne jamais entrer en conflit avec `tale-db` sur 5432. - `tale-sandbox-llm-gateway` — la gateway LLM pour les agents de code en sandbox (image externe pinnée). - `tale-sandbox-egress` et `tale-sandbox` — le plan sandbox. Conteneurs Run-code derrière un proxy de sortie (ouvert par défaut ; verrouillable avec `SANDBOX_EGRESS_ALLOWLIST`), aussi le runtime de navigateur headless que le backend convex appelle pour le rendu web et la génération de documents. La stack est désormais entièrement TypeScript — il n'y a pas de service Python dans le graphe. [Architecture des conteneurs](/fr/self-hosted/operate/container-architecture) creuse qui possède quoi. ## Surcharges Les personnalisations d'opérateur appartiennent à un overlay supplémentaire, pas à des édits sur les fichiers livrés. Crée un `compose.local.yml` avec les surcharges dont tu as besoin : ```yaml services: platform: environment: - LOG_LEVEL=debug ``` Démarre la pile avec l'overlay local superposé en dernier : ```bash docker compose -f compose.yml -f compose.local.yml up -d ``` Ce motif garde `git pull` propre — pas de conflits de merge sur les fichiers livrés. Le même motif fonctionne pour tout montage de volume personnalisé, port personnalisé, ou surcharge d'environnement. ## Profils Un service du fichier de base utilise un profil Docker Compose. Les profils permettent à un service d'exister dans le graphe mais de ne pas démarrer tant que son profil n'est pas activé. Le profil en usage est `controller` — le sidecar `tale-controller`, à activer explicitement, qui redémarre le conteneur convex sur une requête signée pour qu'un changement de résidence des données s'applique sans donner à la plateforme l'accès au socket Docker. Active-le avec : ```bash docker compose --profile controller up -d ``` ## Où ça s'inscrit La référence compose est la grille de l'opérateur pour l'arbre source. Pour l'intérieur de chaque conteneur, la page [Architecture des conteneurs](/fr/self-hosted/operate/container-architecture) couvre les responsabilités ; pour les variables que les conteneurs lisent au démarrage, la [Référence d'environnement](/fr/self-hosted/configuration/environment-reference) est la source de vérité. # Installation Linux serveur de production Source: https://tale.dev/docs/fr/self-hosted/install/linux-server Ce parcours prend la forme du [démarrage rapide](/fr/self-hosted/install/quickstart) et la durcit pour le trafic de production. Le résultat est un seul hôte Linux qui fait tourner Tale derrière du vrai TLS, avec un pare-feu, un utilisateur opérateur non-root, et les défauts opérationnels que l'équipe devrait toucher avant de pointer des utilisateurs sur l'URL. Le parcours vise un Ubuntu LTS récent ou Debian ; les commandes se traduisent une-pour-une vers les distros de la famille RHEL avec `dnf` au lieu d'`apt`. Ne saute rien — l'ordre compte, et chaque étape suppose que la précédente est tombée proprement. ## Avant de commencer Il te faut : - Une VM ou un hôte bare-metal avec au moins 8 Go de RAM, 4 vCPU et 100 Go de disque. Le stockage croît avec les pièces jointes et les connaissances. - Un enregistrement DNS A qui pointe vers l'IP publique de l'hôte. Sans DNS, Let's Encrypt ne peut pas émettre un certificat. - Les ports 80, 443 joignables depuis l'internet public pour l'émission TLS ; SSH sur le port que ta politique opérateur indique. - Sudo sur l'hôte. ## Étape 1 — Provisionner la machine Mets à jour et installe les fondations : ```bash sudo apt update && sudo apt upgrade -y sudo apt install -y curl git ufw ``` Crée un utilisateur opérateur non-root nommé `tale` : ```bash sudo adduser tale sudo usermod -aG sudo,docker tale ``` Bascule vers cet utilisateur (`sudo su - tale`) pour le reste du parcours. Opérer Tale en root tire un rayon d'impact plus large pour aucun bénéfice ; le reste des étapes suppose l'utilisateur `tale`. ## Étape 2 — Installer Docker ```bash curl -fsSL https://get.docker.com | sudo sh sudo systemctl enable --now docker ``` Vérifie avec `docker run hello-world`. Si l'utilisateur ne peut pas lancer docker sans sudo, déconnecte-toi et reconnecte-toi pour reprendre l'appartenance au groupe `docker`. ## Étape 3 — Configurer le pare-feu et le chemin inverse Autorise seulement ce dont Tale a besoin : ```bash sudo ufw default deny incoming sudo ufw default allow outgoing sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable ``` Si tu places Tale derrière un reverse-proxy existant sur le même hôte (rare sur une installation sur un seul hôte), règle `TLS_MODE=external` dans `.env` et ajuste le pare-feu en conséquence. Le conteneur Caddy à l'intérieur de Tale termine TLS par défaut. ## Étape 4 — Récupérer Tale ```bash git clone https://github.com/tale-project/tale.git cd tale cp .env.example .env ``` Règle `HOST`, `SITE_URL`, et génère les quatre secrets comme dans le [démarrage rapide](/fr/self-hosted/install/quickstart). Le diff production par rapport au démarrage rapide vit dans l'étape 5 (TLS) et les crochets opérationnels à la fin de ce parcours. ## Étape 5 — TLS via Let's Encrypt Ouvre `.env` et règle : | Variable | Valeur | | ----------- | ------------------------ | | `TLS_MODE` | `letsencrypt` | | `TLS_EMAIL` | Une boîte ops que tu lis | Caddy émet et renouvelle le certificat automatiquement en utilisant l'enregistrement DNS des prérequis. Le premier démarrage attend le certificat ; compte un délai d'une minute sur le premier `docker compose up -d` pendant que le défi ACME se joue. ## Étape 6 — Premier démarrage ```bash docker compose up -d docker compose ps ``` Chaque service devrait être `running` ou `healthy`. Parcours **Étape 4 — Créer le premier admin** depuis le [démarrage rapide](/fr/self-hosted/install/quickstart) pour atterrir dans le dashboard. Ouvre `SITE_URL` en `https://` — le navigateur ne devrait pas avertir au sujet du certificat. ## Étape 7 — Crochets opérationnels Avant de pointer des utilisateurs sur l'URL, trois crochets te facilitent la vie plus tard : - **Sauvegardes.** Pointe ton outillage de snapshot existant vers `db-data` et le volume du stockage objet — voir [Sauvegardes et restauration](/fr/self-hosted/operate/backups-and-restore). - **Logs.** Tale logue sur stdout. Si l'hôte a journald, `journalctl -u docker` transporte tout ; sinon, pipe vers ton agrégateur. - **Métriques.** Règle `METRICS_BEARER_TOKEN` dans `.env` et scrape `/metrics` depuis ton Prometheus — voir [Configuration de l'observabilité](/fr/self-hosted/configuration/observability-config). ## Tableau des ports | Port | Direction | Objet | Requis | | ---- | --------- | ----------------------------------------------- | -------------- | | 22 | entrant | SSH | oui, restreint | | 80 | entrant | HTTP, sert pour ACME et 301 vers HTTPS | oui | | 443 | entrant | HTTPS, trafic principal | oui | | 53 | sortant | DNS | oui | | 443 | sortant | fournisseurs de modèles, récupérations d'images | oui | ## Dépannage - **L'émission Let's Encrypt échoue.** Le DNS doit résoudre vers l'IP publique de cet hôte depuis l'internet public, et le port 80 doit être joignable depuis l'internet public. Lance `curl -I http://$HOST` depuis une autre machine ; s'il atteint le défi Caddy, le chemin marche. - **Les conteneurs ne peuvent pas joindre les fournisseurs de modèles.** Le pare-feu sortant de l'hôte bloque peut-être ; vérifie avec `docker compose exec platform curl -I https://api.openai.com`. - **Les renouvellements TLS échouent plus tard.** Caddy renouvelle 30 jours avant l'expiration ; les échecs apparaissent dans `docker compose logs proxy`. Les deux causes fréquentes sont une boîte `TLS_EMAIL` expirée et un changement DNS qui a cassé l'enregistrement. ## Où ça s'utilise Tu as maintenant une installation de forme production sur un seul hôte. Deux suites doivent figurer au calendrier — [Sauvegardes et restauration](/fr/self-hosted/operate/backups-and-restore) et [Durcissement](/fr/self-hosted/operate/security/hardening). Si ton échelle dépasse un hôte (règle du pouce : environ cent utilisateurs concurrents sur la spec recommandée), l'architecture multi-hôtes vit sur [Architecture des conteneurs](/fr/self-hosted/operate/container-architecture). # Créer le premier admin Source: https://tale.dev/docs/fr/self-hosted/install/first-admin Une instance Tale toute neuve n'a pas encore d'utilisateurs. La première personne qui l'ouvre déroule un assistant de configuration unique qui crée son compte, la connecte, en fait l'**Owner** et nomme la première organisation — aucune clé de bootstrap, aucune promotion manuelle. Ce parcours couvre ce premier lancement, comment les coéquipiers arrivent ensuite, et où obtenir la clé admin du tableau de bord Convex si tu dois un jour inspecter le backend directement. La seule chose à désapprendre des anciennes instructions : la première inscription ne demande plus de clé admin. Tale est sur invitation seulement après le premier compte, donc il n'y a pas non plus de page d'inscription ouverte à verrouiller. ## Avant de commencer Aie l'instance qui tourne et joignable sur `SITE_URL`. Vérifie avec : ```bash docker compose ps ``` Chaque service devrait montrer `running` ou `healthy`. Si l'un est unhealthy, le [dépannage](/fr/self-hosted/operate/observability/troubleshooting) nomme les quatre causes courantes. ## Dérouler l'assistant de configuration Ouvre `SITE_URL`. Comme il n'y a pas encore d'utilisateurs, Tale t'envoie directement dans l'assistant de configuration — il n'y a pas de page d'inscription séparée à chercher, car l'écran de connexion redirige automatiquement une instance vide vers la configuration. L'assistant crée ton compte et te connecte en plein flux, puis nomme ta première organisation. L'étape du fournisseur est optionnelle : saute-la et ajoute une clé plus tard sous **Paramètres > Fournisseurs IA**, ou connecte OpenRouter maintenant pour discuter tout de suite. Obtiens une clé sur [openrouter.ai/keys](https://openrouter.ai/keys). L'étape finale te dépose dans le tableau de bord. ## Confirmer que tu es l'Owner Le premier compte sur une instance neuve est automatiquement l'**Owner** — aucune clé à coller, aucune étape de promotion. Confirme sous **Paramètres > Personnes** que ta ligne porte le badge Owner. ## Comment les nouvelles personnes arrivent Il n'y a pas d'inscription en libre-service. Une fois qu'un Owner existe, `SITE_URL/sign-up` redirige les visiteurs vers l'écran de connexion, donc personne ne peut créer un compte de lui-même. Ajoute les coéquipiers par invitation sous **Paramètres > Personnes** ; chaque invitation porte le rôle avec lequel le nouveau membre démarre. Le modèle de rôles complet est dans [Membres et rôles](/fr/platform/admin/members-and-roles). ## Obtenir la clé admin du tableau de bord Convex La clé admin ne joue aucun rôle dans les étapes ci-dessus — elle ne débloque que le **tableau de bord Convex**, la vue bas niveau de la base de données du backend. La clé est déterministe : elle est dérivée de `INSTANCE_SECRET`, donc elle reste la même d'un redémarrage à l'autre au lieu de tourner. Obtiens-la de la façon qui correspond à ton installation : - Avec la CLI : `tale convex admin` trouve le conteneur platform et imprime la clé. `tale dev` l'imprime aussi une fois les services en bonne santé. - Depuis un clone git : `./scripts/get-admin-key.sh` à la racine du dépôt. Ouvre `SITE_URL/convex-dashboard`, saisis `SITE_URL` comme URL de déploiement, et colle la clé quand on te la demande. ## Dépannage - **L'assistant n'est pas apparu — tu atterris sur l'écran de connexion.** Des utilisateurs existent déjà sur cette instance ; l'assistant ne tourne que sur une instance vraiment vide. Connecte-toi à la place, ou fais-toi inviter par un Owner existant sous **Paramètres > Personnes**. - **Un service est unhealthy.** Le conteneur platform n'est pas entièrement monté. `docker compose ps` dit quel service échoue ; `docker compose logs platform` montre pourquoi. - **Le tableau de bord rejette la clé admin.** La clé est déterministe à partir de `INSTANCE_SECRET`, donc un rejet signifie généralement que `INSTANCE_NAME` et `INSTANCE_SECRET` diffèrent entre les services platform et Convex, ou que l'URL de déploiement est fausse — utilise `SITE_URL`. Régénère avec `tale convex admin` pour être sûr d'avoir copié la valeur actuelle. ## Où ça s'utilise Tu as maintenant un Owner et une organisation, et tu sais que la clé admin est un outil d'inspection du backend, pas une partie de la connexion. Le premier lancement est sans clé par conception : ouvre l'URL, l'assistant te fait Owner, et tous les autres arrivent par invitation. Les étapes suivantes pour le calendrier sont d'inviter le reste des admins (sous **Paramètres > Personnes**), d'ajouter un fournisseur de modèles, et de publier le premier agent — le parcours [Onboarding Cloud](/fr/cloud/onboarding) est identique à partir d'ici, à l'URL près. # Installer la CLI tale Source: https://tale.dev/docs/fr/self-hosted/install/cli-install La CLI `tale` est la façon recommandée de faire tourner et d'exploiter Tale. Le [démarrage rapide](/fr/self-hosted/install/quickstart) l'utilise déjà pour monter une instance en local avec `tale init` et `tale dev` ; cette page est l'autre moitié — installer la CLI sur une station de travail pour qu'elle puisse piloter une instance _distante_ : déployer de nouvelles versions, lancer des migrations et capturer des diagnostics sans que tu aies à te souvenir de chaque invocation `docker compose`. Tout ce que fait la CLI peut aussi se faire directement avec `docker compose` et `ssh`, donc une équipe déjà profondément dans sa propre automatisation peut rester sur compose. Pour tous les autres, la CLI est le chemin le plus court, et le reste de la doc auto-hébergée suppose qu'elle est installée. ## Avant de commencer Il te faut : - Une station de travail sous macOS, Linux ou Windows 10+. - Un accès SSH à l'hôte où tourne ton instance Tale, avec l'utilisateur opérateur capable de lancer `docker compose`. L'installeur télécharge un binaire de release depuis GitHub. Les réseaux d'entreprise qui bloquent les téléchargements de contenu brut doivent autoriser `raw.githubusercontent.com` et `github.com`. ## Étape 1 — 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 ``` Les deux installeurs détectent l'OS et l'architecture CPU, récupèrent le binaire de release correspondant depuis la dernière release GitHub, et le déposent sur le `PATH` (`/usr/local/bin/tale` ou `%LOCALAPPDATA%\Programs\tale\tale.exe`) — quand le répertoire d'installation n'est pas accessible en écriture, l'installeur demande `sudo`. Les binaires de release existent pour macOS sur Apple Silicon et Intel, et pour Linux sur x86_64 et arm64 ; les machines Windows-on-ARM exécutent le binaire x64 via l'émulation intégrée. Sur une architecture sans binaire de release, l'installeur s'arrête avec un message clair et renvoie vers la compilation depuis les sources. Pour fixer une version, règle la variable d'environnement `VERSION` avant de piper dans l'installeur ; pour choisir toi-même le répertoire d'installation, règle `INSTALL_DIR`. | OS | Script d'installeur | | ------- | ------------------------- | | macOS | `scripts/install-cli.sh` | | Linux | `scripts/install-cli.sh` | | Windows | `scripts/install-cli.ps1` | ## Étape 2 — Vérifier ```bash tale --version ``` La CLI imprime sa version. Si la commande n'est pas trouvée, l'installeur a déposé le binaire hors du `PATH` — la sortie de l'installeur nomme le répertoire de destination. ## Étape 3 — Vérifier la configuration Il n'y a pas de `tale config set` — tout ce dont la CLI a besoin vit dans le projet créé par `tale init`. Lance chaque commande `tale` depuis ce répertoire (la CLI remonte l'arborescence pour trouver `tale.json`), et vérifie qu'il se résout : ```bash tale config show ``` L'hôte sur lequel le proxy répond, les réglages TLS et tous les secrets vivent dans le `.env` du projet. Pour changer l'hôte, modifie `HOST` là-bas ou passe `--host` à `tale dev` / `tale deploy`. Pour piloter un hôte distant, pointe le contexte Docker de ton shell (ou `DOCKER_HOST`) dessus — la CLI parle au même endpoint Docker que n'importe quelle commande `docker`. La clé admin du tableau de bord Convex est séparée de la configuration de la CLI — elle ne conditionne jamais l'inscription et elle est déterministe (dérivée de `INSTANCE_NAME` et `INSTANCE_SECRET`, donc identique d'un redémarrage à l'autre). Génère-la avec `tale convex admin` quand tu veux inspecter le backend (voir [Premier admin](/fr/self-hosted/install/first-admin)). ## Étape 4 — Lancer tale deploy ```bash tale deploy ``` `tale deploy` livre toujours la version de la CLI elle-même : il récupère les images de cette version, redémarre les conteneurs affectés dans le bon ordre, et lance les migrations de schéma — pour passer à une autre version, commence par `tale update`. C'est le remplacement pris en charge pour la danse plus longue `docker compose pull && docker compose up -d`. Si tu préfères compose directement, le même effet vit dans [Mises à jour](/fr/self-hosted/operate/upgrades). ## Référence des commandes Le 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**. - Chaque option est **optionnelle** — l'omettre donne le comportement par défaut. - 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. Lance `tale <commande> --help` pour la liste de référence de 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, messages humains sur stderr ; pris en charge par `status`, `config show` et `migrate status`. - `--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 init [directory]` — créer un projet : échafaude 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` — échafauder le projet mais ignorer la génération du `.env`. `tale dev` — démarrer tous les services localement avec un certificat auto-signé. - `-d, --detach` — s'exécuter en arrière-plan au lieu de diffuser les logs. - `-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éploiement blue-green sans interruption de la version actuelle du CLI. Au premier déploiement, il demande ton domaine de production et l'e-mail Let's Encrypt (ou passe `--host`). - `--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. ### 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` — snapshot de tous les volumes de données vers le volume de sauvegardes du projet. Aucun argument. `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` — bouger cette instance Tale vers une nouvelle version : mettre à jour le binaire CLI, puis synchroniser les fichiers projet sur les templates de cette version. Lance `tale deploy` ensuite pour rouler les conteneurs. La CLI s'aligne aussi d'elle-même sur la version de l'instance à chaque commande, donc ceci n'est nécessaire que pour changer délibérément de version. - `-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 et appliquer les migrations de données sûres en attente sur le déploiement en cours — les mêmes étapes idempotentes que chaque déploiement exécute, à la demande. Les sous-commandes donnent un contrôle fin et réversible : `migrate status` montre les migrations appliquées et en attente, `migrate up [--to <version>]` applique celles en attente (les étapes destructives demandent `-y, --yes` ou `--step`), `migrate down --to <version>` revient en arrière. `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_ de retirer aussi la configuration propre à l'utilisateur (`~/.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. - `-f, --force` — ignorer l'invite de confirmation (supprime uniquement le binaire ; les nettoyages optionnels nécessitent toujours `--purge`). - `--purge` — retirer aussi `~/.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` — gérer la configuration du CLI. Utilise le sous-commande `show` pour afficher la configuration résolue. ### Avancé `tale auth reset-owner` — réinitialiser les identifiants du compte propriétaire. - `-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. `tale convex admin` — générer une clé admin pour le tableau de bord Convex. Aucun argument. ## 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. - **Le tableau de bord Convex rejette la clé admin.** L'inscription ne demande jamais la clé — seul le tableau de bord le fait. La clé est déterministe (dérivée de `INSTANCE_NAME` et `INSTANCE_SECRET`), donc un rejet signifie généralement que ces valeurs diffèrent entre les services platform et Convex, ou que l'URL de déploiement est fausse — utilise `SITE_URL`. Régénère avec `tale convex admin` pour être sûr d'avoir copié la valeur actuelle. - **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`). ## Où ça s'utilise Une fois la CLI branchée, la surface quotidienne de l'opérateur se réduit à une poignée de sous-commandes. Les pages à lire ensuite dépendent de pourquoi tu es venu — [Mises à jour](/fr/self-hosted/operate/upgrades) pour les bumps de version, [Sauvegardes et restauration](/fr/self-hosted/operate/backups-and-restore) pour les exercices de snapshot, [Architecture des conteneurs](/fr/self-hosted/operate/container-architecture) pour ce que la CLI redémarre quand elle déploie. # Documentation Tale Source: https://tale.dev/docs/fr Tale est l’orchestrateur pour agents IA. Tu discutes avec des modèles sur tes propres documents, tu construis des agents qui prennent une tâche en charge de bout en bout, tu lances des automatisations en arrière-plan et tu gères les conversations clients depuis une seule boîte de réception — avec les fournisseurs d’IA de ton choix et tes données ancrées dans une région que tu contrôles. Chaque fonctionnalité, chaque API et chaque rôle est identique entre les deux éditions ; la seule différence est qui exploite la stack. Commence par le démarrage rapide, puis suis le parcours qui correspond à ton rôle. <CardGroup cols="1"> <Card title="Démarrage rapide — ta première réponse d’agent en 5 minutes" icon="zap" href="/fr/get-started/quickstart"> D’une instance qui tourne à une réponse dans le chat, sur Cloud ou sur ta propre machine. </Card> </CardGroup> ## Choisis ton parcours Quatre parcours pour le premier jour, un par rôle. Chacun prend environ quinze minutes et se termine sur quelque chose qui fonctionne. <CardGroup cols="2"> <Card title="J’utilise Tale" icon="message-circle" href="/fr/get-started/members"> Ton premier chat, ton premier document, ton premier projet — le premier jour du membre. </Card> <Card title="Je construis des agents" icon="bot" href="/fr/get-started/editors"> Publie un agent minimal et regarde-le répondre dans le chat — le premier jour de l’éditeur. </Card> <Card title="J’intègre Tale" icon="code" href="/fr/get-started/developers"> Crée une clé API et envoie ta première requête authentifiée — le premier jour du développeur. </Card> <Card title="Je gère l’espace de travail" icon="shield" href="/fr/get-started/admins"> Monte l’espace de travail, invite l’équipe, connecte un fournisseur — le premier jour de l’admin. </Card> </CardGroup> ## Choisis ton édition <CardGroup cols="2"> <Card title="Cloud" icon="cloud" href="/fr/cloud"> Tale exploite la stack — choisis cette voie quand exploiter de l’infrastructure n’est pas là où ton équipe doit passer ses heures. </Card> <Card title="Auto-hébergé" icon="server" href="/fr/self-hosted"> Installe Tale dans ton propre VPC, sur du matériel on-premise ou dans un environnement coupé du réseau. </Card> </CardGroup> ## Aller plus loin <CardGroup cols="3"> <Card title="Plateforme" icon="layout-dashboard" href="/fr/platform"> La référence canonique des fonctionnalités, identique pour Cloud et auto-hébergé. </Card> <Card title="Tutoriels" icon="route" href="/fr/tutorials/overview"> Des parcours indexés par rôle, de « je veux faire X » au résultat qui fonctionne. </Card> <Card title="Développement" icon="terminal" href="/fr/develop/overview"> REST API, webhooks, SDK d’intégration, workflows pour les contributeurs. </Card> </CardGroup> ## Où cela s’inscrit Une fois un parcours de démarrage terminé, le reste de la documentation est à un clic : [Plateforme](/fr/platform) est la référence canonique de chaque fonctionnalité visible par l’utilisateur, et les [Tutoriels](/fr/tutorials/overview) approfondissent des tâches complètes. Le code source, les issues et les annonces de release vivent sur [GitHub](https://github.com/tale-project/tale). # Développement Source: https://tale.dev/docs/fr/develop/overview Développement est la section pour les intégrateurs et les contributeurs — tous ceux qui branchent Tale sur un autre système, construisent au-dessus de l’API ou livrent une modification du code source. Les pages ici décrivent la surface externe (REST, webhooks, endpoints compatibles OpenAI) et le workflow de contribution. Si tu es à l’intérieur du produit avec le rôle Développeur (construction d’agents, d’automatisations, d’outils sur mesure), l’onglet Plateforme couvre ton quotidien ; Développement sert quand tu es à l’extérieur du produit et que tu lui parles via le fil. ## Pages de cette section <CardGroup cols="2"> <Card title="Référence API" icon="code" href="/fr/develop/api-reference"> Endpoints, authentification, endpoints compatibles OpenAI, modèle d’erreur, versionnage. </Card> <Card title="Webhooks" icon="webhook" href="/fr/develop/webhooks"> Sortants (Tale → toi) et entrants (toi → Tale), signature, idempotence, retraitements. </Card> <Card title="Développement assisté par IA" icon="sparkles" href="/fr/develop/ai-assisted-development"> Utiliser les agents Tale pour écrire des workflows Tale, les fichiers de skill `.agents/`. </Card> <Card title="Intégrations" icon="plug" href="/fr/develop/integrations"> Intégrations tierces vues côté développeur. </Card> <Card title="Page de statut" icon="activity" href="/fr/develop/status-page"> Rapport d’incident pour Cloud, pointeurs de métriques pour auto-hébergé. </Card> <Card title="Limites de débit" icon="gauge" href="/fr/develop/rate-limits"> Limites par clé, par IP, par organisation, et comment lire un 429. </Card> </CardGroup> ## Où cela s’inscrit Développement est la section la plus petite, parce que la plupart des utilisateurs n’en ont jamais besoin ; le public se concentre sur deux rôles (Développeur dans le produit, contributeur en dehors), mais elle est porteuse pour les deux. Si tu branches quelque chose d’externe sur Tale, [Référence API](/fr/develop/api-reference) est la première lecture ; si tu contribues au code source, [Contribuer](/fr/self-hosted/contributing-docker) — sous l’onglet Auto-hébergé — est la bonne. # Référence API Source: https://tale.dev/docs/fr/develop/api-reference L'API Tale est la surface vers laquelle se tournent les intégrateurs quand ils sont hors du produit et veulent le scripter. L'authentification est une clé API dans un en-tête ; le plan de données est du JSON sur HTTPS ; un sous-ensemble des endpoints chat parle le format Chat Completions d'OpenAI, donc les bibliothèques clientes OpenAI existantes fonctionnent sans changement. Cette page est l'inventaire canonique de la surface API, du modèle d'auth et de la forme des erreurs. Elle n'énumère pas chaque champ de payload — cela vit à côté de chaque groupe d'endpoints sur les sous-pages liées. Lis-la avant d'appeler l'API ; reviens-y quand tu n'es pas sûr de quel en-tête porte la clé ou de ce que signifie un 429. ## Une requête mise en pratique La requête utile la plus courte — lister les agents que ta clé peut voir — tient en un curl : ```bash curl -sS https://your-host.example.com/api/v1/agents \ -H "Authorization: Bearer $TALE_API_KEY" \ -H "Accept: application/json" ``` Une réponse réussie est du JSON : `{ "agents": [ { "id": "...", "name": "...", "visibleInChat": true, ... }, ... ] }`. Chaque endpoint list retourne la même forme — un objet de premier niveau avec une propriété tableau nommée d'après la ressource. ## Authentification Les clés API sont émises dans l'UI sous **Paramètres > Clés API** par toute personne avec le rôle Développeur ou supérieur. Chaque clé a un nom, un propriétaire et une portée ; la portée suit le rôle de l'utilisateur émetteur au moment de la création. Les clés sont affichées une fois à la création ; Tale n'affiche jamais à nouveau la clé brute. Passe la clé comme bearer token : `Authorization: Bearer <clé>`. La clé authentifie la requête ; le contexte d'organisation est déduit de la clé. Une clé ne peut pas être utilisée hors de son organisation émettrice. Les cookies authentifient la session navigateur ; les appels API depuis le navigateur dans le produit utilisent les cookies. Les scripts côté serveur utilisent la clé API. ## Groupes d'endpoints | Groupe | Méthode | Chemin | Auth requise | Notes | | ---------------------------------------------------------- | -------- | ---------------------------- | ------------ | ---------------------------------------------------------- | | Agents | diverses | `/api/v1/agents/...` | Clé API | List, get, run. | | Chat | diverses | `/api/v1/chat/...` | Clé API | Stream de complétions chat contre un agent ou un modèle. | | Compatible OpenAI | POST | `/api/v1/chat/completions` | Clé API | Forme Chat Completions OpenAI ; utilise les SDK existants. | | Compatible OpenAI | POST | `/api/v1/images/generations` | Clé API | Génère des images ; forme Images OpenAI. | | Compatible OpenAI | GET | `/api/v1/models` | Clé API | Liste les modèles disponibles au format OpenAI. | | Workflows | diverses | `/api/v1/workflows/...` | Clé API | Lancer par slug, plannings, webhooks, exécutions. | | Webhooks de workflow | POST | `/api/workflows/wh/<token>` | Jeton d'URL | Déclencher un workflow par webhook depuis l'extérieur. | | Connaissances — Documents | diverses | `/api/v1/documents/...` | Clé API | Upload, list, get, delete. | | Connaissances — Clients, Produits, Fournisseurs, Sites web | diverses | `/api/v1/<entity>/...` | Clé API | List, get, create, update. | | Conversations | diverses | `/api/v1/conversations/...` | Clé API | List par statut, get, écriture de messages. | | Fichiers | diverses | `/api/v1/files/...` | Clé API | Upload, get, delete. Utilisé par les téléversements. | Les formes exactes de champs pour chaque endpoint vivent dans le document OpenAPI que la plateforme émet à la compilation ; charge-le dans une visionneuse Swagger ou Stoplight pour voir les schémas de requêtes et de réponses avec exemples. Les groupes d'endpoints du tableau ci-dessus sont l'inventaire de haut niveau ; le document OpenAPI est la référence au niveau des champs. ## Endpoints compatibles OpenAI `POST /api/v1/chat/completions` accepte un payload en forme Chat Completions OpenAI et retourne une réponse streaming ou non en même forme. Le champ `model` est interprété comme l'ID d'agent — passe un ID d'agent pour router via les instructions, connaissances et outils de cet agent. Passe un nom de modèle brut (ex. `gpt-4o`) pour contourner les agents et appeler le fournisseur directement. Les SDK OpenAI existants marchent avec un changement : pointe l'URL de base sur `https://your-host.example.com/api/v1` et substitue la clé API. Le streaming utilise les Server-Sent Events. ### Vision Pour envoyer une image, donne au message utilisateur un `content` en tableau de parties plutôt qu'une chaîne — une partie `text` plus une ou plusieurs parties `image_url`, chacune portant une URL `data:` ou une URL `https` publique. C'est la forme vision standard d'OpenAI, donc un SDK qui construit déjà des messages multimodaux n'a besoin d'aucun changement. Un `content` en chaîne simple marche toujours pour les tours en texte seul ; seule l'entrée image exige la forme tableau. ### Génération d'images `POST /api/v1/images/generations` prend `{ model, prompt, n?, response_format? }` et retourne la forme Images OpenAI — `{ created, data: [...] }`. `response_format` vaut `url` (par défaut — chaque entrée est une URL de téléchargement) ou `b64_json` (chaque entrée est des octets d'image en base64) ; `n` est plafonné à 4. Appelle-le via le `images.generate` de n'importe quel SDK OpenAI. Passer un modèle de génération d'images à `/api/v1/chat/completions` marche aussi : l'image générée revient sur le message assistant sous `choices[0].message.images[]` — chacune une `image_url` — suivant la convention des passerelles capables d'images, de sorte que l'appel est facturé contre une image retournée plutôt que contre une image perdue. Pour éditer une image existante, envoie cette même requête avec une partie `text` et une partie `image_url` portant une URL `data:` à un modèle qui prend en charge l'édition ; l'image éditée revient de la même façon. Seules les URL `data:` sont lues comme entrées d'édition — Tale ne va jamais chercher une URL d'image `http` côté serveur. ## Modèle d'erreur Les erreurs atterrissent en JSON : `{ "error": { "code": "<symbole>", "message": "<humain>", "details"?: { ... } } }`. Le statut HTTP est l'un de : - **400** — requête mal formée (champ manquant, mauvais type). - **401** — clé API manquante ou invalide. - **403** — la clé est valide mais n'a pas le rôle requis pour l'action. - **404** — la ressource n'existe pas ou la clé ne peut pas la voir. - **409** — conflit (ex. clé d'idempotence dupliquée avec un body différent). - **422** — sémantiquement invalide (ex. l'agent référencé par un déclencheur de workflow a été archivé). - **429** — limite de débit atteinte. Voir [Limites de débit](/fr/develop/rate-limits). - **500** — erreur interne. Le champ `details` du body contient un ID de requête citable au support. Le `code` est un symbole (`unauthorized`, `forbidden`, `agent_not_found`, …) ; le `message` est lisible. Les clients doivent brancher sur `code`, pas sur le message humain. ## Idempotence Chaque endpoint d'écriture accepte un en-tête `Idempotency-Key`. La première requête avec une clé donnée réussit ; les requêtes suivantes avec la même clé retournent la même réponse sans réexécuter. La clé est valide 24 heures. L'idempotence est obligatoire pour les appels de déclencheur webhook — le système source doit envoyer une clé stable par événement logique pour que les retries ne tirent pas le workflow en double. ## Versionnage L'API est versionnée par préfixe d'URL : aujourd'hui, `/api/v1/`. Les changements cassants ship sous un nouveau préfixe ; l'ancien reste disponible pendant au moins une version mineure. Les ajouts non cassants atterrissent dans le préfixe courant. Les notes de version nomment la version d'API contre laquelle chaque release ship ; fige ta bibliothèque cliente sur la version courante en production. ## Où cela s'inscrit L'API est la couture entre Tale et tout ce qui est dehors. Les webhooks sont l'autre moitié — pour les événements que Tale doit te pousser, ou pour toi à pousser vers les workflows de Tale, la [référence Webhooks](/fr/develop/webhooks) couvre les règles de signature et d'idempotence. Si tu construis dans le produit avec le rôle Développeur — agents, workflows, outils sur mesure — l'[onglet Plateforme](/fr/platform) est ton quotidien ; cette page est pour l'extérieur. # Limites de débit Source: https://tale.dev/docs/fr/develop/rate-limits L'API REST de Tale est limitée par clé et par org. Les défauts sont taillés pour du trafic applicatif normal — les bursts passent, le martelage soutenu renvoie 429. Quand tu atteins une limite, la réponse porte les en-têtes dont tu as besoin pour reculer proprement ; le mauvais geste (retry sans délai, retry sans fin) ne fait qu'aggraver la régulation. Lis ceci quand tu câbles un client qui appelle l'API planifié ou sous charge. Reviens-y quand une intégration jusque-là saine se met à renvoyer 429 — la réponse est presque toujours un backoff manquant, pas un manque de capacité accordée. ## Un 429 mis en pratique L'échange utile le plus court est une requête qui dépasse le budget de sa clé. Le serveur renvoie : ```http HTTP/1.1 429 Too Many Requests Content-Type: application/json Retry-After: 12 X-RateLimit-Limit: 120 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1717000060 { "error": { "code": "rate_limited", "message": "Rate limit exceeded. Try again in 12 seconds." } } ``` `Retry-After` est l'attente faisant foi — dors au moins ce temps avant la prochaine tentative. `X-RateLimit-Reset` est le timestamp Unix auquel la fenêtre se recharge. Le `code` dans le body est `rate_limited` ; les clients doivent brancher sur le code, pas parser le message. ## Limites par défaut | Surface | Budget | Bucket | | ------------------------------------ | ----------------------------- | ---------------- | | API REST (`/api/v1/*`) | 120 requêtes / minute / clé | Token, burst 200 | | Chat compatible OpenAI | 30 requêtes / minute / clé | Token, burst 50 | | Listage de modèles compatible OpenAI | 120 requêtes / minute / clé | Token, burst 200 | | Webhooks de déclencheur de workflow | 60 requêtes / minute / clé | Token, burst 100 | | Webhooks d'agent | 30 requêtes / minute / clé | Token, burst 50 | | Téléversement de fichier | 50 requêtes / minute / membre | Fenêtre fixe | | Envoi de courriel | 100 messages / heure / org | Token, burst 120 | Les token buckets autorisent un burst court au-dessus du débit — utile pour les imports en lot — puis se stabilisent au débit soutenu. Les fenêtres fixes se rechargent à la frontière de la minute ; une requête à 14:59:59 et une autre à 15:00:00 passent toutes les deux. Choisis les buckets en conséquence : une UI qui se monte une fois par minute lit comme un token, pas comme 60 sur une fenêtre. ## Plafonds par org Tale Cloud applique un plafond doux par org au-dessus des budgets par clé, ajusté au plan de l'org. Le plafond protège contre une clé emballée en s'assurant qu'un seul client ne peut pas consommer tout le budget de l'org. Les instances auto-hébergées n'ont pas de plafond par org par défaut — les budgets par clé ci-dessus sont le seul plancher. Quand il te faut un budget par clé plus haut pour une charge connue sur Cloud, demande au support avec le nom de la clé et le débit soutenu attendu. Les octrois de capacité sont par clé, pas par org. ## Stratégie de retraitement La bonne stratégie est un backoff exponentiel avec jitter, plafonné à la valeur `Retry-After` quand elle est présente : 1. Sur 429, lis `Retry-After` et dors au moins ce temps. 2. Si `Retry-After` est absent (rare), démarre à 1 s et double à chaque 429 suivant, plafonné à 60 s. 3. Ajoute jusqu'à 25 % de jitter pour que des clients concurrents ne retraitent pas en lock-step. 4. Abandonne après la huitième tentative et fais remonter l'échec — le bucket est saturé et continuer ne servira à rien. L'idempotence compte ici : chaque endpoint d'écriture accepte un en-tête `Idempotency-Key`. Pose une clé stable par opération logique pour que les retries ne fassent pas double feu quand la requête initiale a réussi mais que la réponse s'est perdue. Voir [Référence API](/fr/develop/api-reference) pour la fenêtre d'idempotence. ## Où cela s'inscrit Les limites de débit sont la manière dont Tale reste disponible quand un client se conduit mal. La [Référence API](/fr/develop/api-reference) nomme le 429 dans le modèle d'erreur et renvoie ici pour les règles ; la [Référence Webhooks](/fr/develop/webhooks) couvre la politique de retraitement correspondante sur les livraisons sortantes. Si ton trafic est mal formé pour les défauts et qu'un octroi du support ne suffit pas, l'onglet [Auto-hébergé](/fr/self-hosted/overview) est l'autre réponse — exécuter la plateforme sur ta propre infra lève les plafonds imposés par le Cloud. # API WebDAV Source: https://tale.dev/docs/fr/develop/webdav-api Tale expose le dépôt de documents sous `/dav/<orgSlug>/` comme point de terminaison WebDAV Class 2 lecture-écriture (RFC 4918). Cette page est la référence du protocole — la surface filaire dont un implémenteur de client ou un outil tiers a besoin pour intégrer. Pour le guide de configuration utilisateur final et les instructions par client, voir [Plateforme > Intégrations > WebDAV](/fr/platform/integrations/webdav). ## Schéma d’URL ```text /dav/<orgSlug>/documents/<path> R/W arbre de documents actifs /dav/<orgSlug>/.trash/<path> R/O documents soft-supprimés (vue corbeille) /dav/<orgSlug>/ R/O collection contenant les deux ci-dessus ``` Les segments sont URL-encodés. Le serveur rejette les segments contenant `/`, `\`, NUL, ou les noms relatifs `.` et `..`. Chaque segment doit faire 1–255 octets. Le `orgSlug` correspond à `[a-zA-Z0-9_-]{1,64}`. La politique de slash final suit la convention WebDAV : les collections (dossiers) sont référencées avec un slash final, les ressources (fichiers) sans. Beaucoup de clients normalisent à la volée ; le serveur accepte les deux formes à la résolution et émet la forme canonique dans les réponses PROPFIND. ## Authentification HTTP Basic uniquement. Le champ nom d’utilisateur peut être n’importe quelle valeur non vide — le mot de passe applicatif est la vraie information d’identification, et le serveur ne compare pas le nom d’utilisateur à ton enregistrement de compte. Utiliser l’e-mail de ton compte Tale est la convention pour la lisibilité des journaux d’audit, et les clients qui pré-remplissent depuis le trousseau attendent une chaîne en forme d’e-mail, mais la décision d’authentification se fait uniquement sur le mot de passe. Le mot de passe est un **mot de passe applicatif** généré sous Paramètres > WebDAV. Le mot de passe principal n’est pas accepté sur ce point de terminaison. ```http Authorization: Basic <base64(email-ou-autre:mot-de-passe-applicatif)> ``` Les mots de passe applicatifs sont hachés avec HMAC-SHA256 sous le secret de déploiement `WEBDAV_APP_PASSWORD_HMAC_KEY`. La clé est dérivée de manière déterministe depuis `INSTANCE_SECRET` par l’entrypoint de la plateforme (prod) et `server.ts` (dev), donc les opérateurs n’ont pas à la définir manuellement ; une valeur explicite dans `.env` remplace la valeur dérivée. La recherche restreint via les quatre premiers caractères du mot de passe (stockés à côté du hash pour une recherche indexée) et vérifie avec une comparaison HMAC à temps constant. Chaque requête authentifiée vérifie aussi que l’utilisateur est membre actif de l’organisation dans l’URL — une ligne périmée (appartenance retirée après l’émission) est rejetée avec `403`. `OPTIONS` est la seule méthode autorisée sans authentification ; les clients l’utilisent pour sonder la capacité DAV avant de se connecter. ## Méthodes | Méthode | Comportement | Auth | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | OPTIONS | Annoncer les capacités. Renvoie `DAV: 1, 2`, `Allow: …`, et `Microsoft-Server-WebDAV-Extensions: 1` pour la compatibilité Windows. | Anonyme OK | | PROPFIND | Lister une ressource (Depth 0) ou les enfants directs d’une collection (Depth 1). La liste de propriétés émise est documentée plus bas. **Depth: infinity est rejeté avec 403** pour éviter des réponses sans borne. | Requise | | PROPPATCH | Renvoie succès 207 par propriété sans stocker les valeurs. Les dead properties ne sont pas persistées en v1 ; PROPPATCH réussit de manière optimiste pour la compatibilité client. | Requise | | GET / HEAD | Streamer le blob du document. Pose `Content-Type`, `Content-Length`, `ETag` et `Last-Modified`. GET sur une collection renvoie 405. | Requise | | PUT | Créer ou remplacer un document. Le nouveau blob est stocké dans le stockage Convex avec déduplication par hash ; la ligne du document reçoit `sourceProvider: "webdav"`. Renvoie 201 à la création, 204 à l’écrasement. | Requise | | DELETE | Soft-supprimer un document (`lifecycleStatus: "trashed"`) ou un dossier (corbeille en cascade sur les documents contenus, hard-supprime les lignes de dossier). Renvoie 204. | Requise | | MKCOL | Créer un dossier sous un parent existant. Corps vide uniquement. Renvoie 201, 405 si la cible existe, 409 si le parent manque. | Requise | | MOVE | Renommer ou déplacer. Atomique pour les documents. Pour les dossiers, met à jour le `parentId` du dossier déplacé. Respecte `Overwrite: T/F` et `If`. Renvoie 201 (nouvelle destination) ou 204 (écrasement). | Requise | | COPY | Copie côté serveur. Les copies de documents réutilisent l’identifiant de stockage Convex (déduplication). Les copies de dossiers sont récursives. Respecte `Overwrite` et `If`. | Requise | | LOCK | Verrou d’écriture Class 2 exclusif ou partagé. Timeout depuis le header `Timeout: Second-N`, plafonné à 3600. Rafraîchissement en renvoyant LOCK avec `If: (<opaquelocktoken:...>)` et un corps vide. | Requise | | UNLOCK | Libérer un verrou par son jeton. Seul le propriétaire peut libérer. Renvoie 204. | Requise | `HEAD` partage son handler avec `GET`, corps en moins. ## Propriétés PROPFIND renvoie ces propriétés vivantes pour chaque ressource : - `resourcetype` — `<collection/>` sur les dossiers, vide sur les documents. - `displayname` — le nom du dossier ou le titre du document. - `getlastmodified` — horodatage RFC 1123. Les documents utilisent `sourceModifiedAt` s’il est défini, sinon l’heure de création de la ligne. - `creationdate` — ISO 8601 de l’heure de création de la ligne. - `getcontenttype` — documents uniquement ; le MIME type au moment du téléversement. - `getcontentlength` — documents uniquement ; en octets. - `getetag` — documents uniquement ; le hash de contenu s’il est connu, sinon l’identifiant du document. - `supportedlock` — annonce le support des verrous d’écriture exclusifs. - `lockdiscovery` — présent sur les ressources avec verrous actifs. Les dead properties ne sont pas stockées. PROPPATCH renvoie 200 pour une dead property définie seule, mais définir une propriété live/protégée renvoie un 403 par propriété (`cannot-modify-protected-property`), et toutes les dead properties de la même requête sont alors signalées en 424 Failed Dependency (RFC 4918 §9.2 atomicité). Aucune valeur n’est jamais persistée. ## Sémantique des verrous Les verrous vivent dans leur propre table Convex, indexés par `(organizationId, resourcePath)`. La forme filaire est `opaquelocktoken:<uuid>`. Le serveur : - Plafonne le timeout à 3600 secondes. Les requêtes pour des fenêtres plus longues sont silencieusement bornées. - Traite `LOCK` avec un header `If: (<opaquelocktoken:UUID>)` et un corps vide comme un refresh — l’expiration du verrou existant est repoussée. - Renvoie `412 Precondition Failed` au refresh si le jeton fourni est inconnu. - Renvoie `423 Locked` sur `PUT / DELETE / MOVE / COPY / MKCOL / PROPPATCH` contre un chemin verrouillé quand la requête n’a pas de header `If` correspondant. - Renvoie `412 Precondition Failed` si le jeton `If` fourni ne correspond pas au verrou vivant. - Expire les verrous paresseusement — la requête de lookup renvoie null pour les lignes expirées et planifie une suppression fire-and-forget. - Hard-supprime tout verrou détenu sous un mot de passe applicatif quand ce mot de passe est révoqué. `UNLOCK` requiert à la fois un header `Lock-Token` valide et que l’utilisateur soit le propriétaire du verrou. ## Codes de statut - `200` — OPTIONS, GET, HEAD, LOCK, refresh LOCK, PROPPATCH (par propriété) - `201` — création PUT, MKCOL, MOVE/COPY vers une nouvelle destination - `204` — DELETE, UNLOCK, écrasement PUT, écrasement MOVE/COPY - `207` — PROPFIND, PROPPATCH (enveloppe multi-status) - `400` — header `Destination` / `If` / `Lock-Token` / `Timeout` mal formé - `401` — Basic auth absente ou invalide - `403` — Depth: infinity rejeté ; tentative d’écriture .trash ; suppression/déplacement de la racine ; mauvais propriétaire de mot de passe applicatif sur UNLOCK ; utilisateur pas membre de l’org ; MOVE/COPY sur lui-même ou dans son propre sous-arbre ; `Destination` cross-org - `404` — ressource introuvable - `405` — GET sur une collection ; PUT sur un chemin de collection ; MKCOL sur un chemin existant ; MKCOL racine - `409` — MKCOL, MOVE ou COPY quand le parent de destination n’existe pas - `412` — non-correspondance de jeton `If` ; précondition `If-Match` / `If-None-Match` échouée ; MOVE/COPY avec `Overwrite: F` sur une destination existante - `413` — corps PUT au-delà de la limite de taille, ou un corps XML (PROPFIND / PROPPATCH / MKCOL / LOCK) au-delà de 64 Ko - `415` — MKCOL avec corps XML non vide (extended MKCOL non implémenté) - `423` — écriture tentée sur un chemin verrouillé sans `If` correspondant - `502` — `Destination` cross-host ; fetch proxy stockage échoué - `503` — limite du nombre de LOCK dépassée pour le mot de passe applicatif (avec `Retry-After`) - `507` — sous-arbre de dossier trop volumineux pour être supprimé, déplacé ou copié en une seule requête ## Conformité - DAV Class **1** (base) : complète. - DAV Class **2** (verrouillage) : complète, avec le comportement d’expiration paresseuse décrit ci-dessus. - DAV Class **3** (calendrier, contacts, recherche, ACL) : non implémentée. Le serveur annonce `DAV: 1, 2` dans la réponse OPTIONS. ## Limites - `Depth: infinity` sur PROPFIND est rejeté avec `403`. - `Timeout: Second-N` sur LOCK est borné à `[1, 3600]`. - La taille du corps PUT est plafonnée à **5 Go** par défaut (`413` au-delà), appliquée à la fois au reverse-proxy et dans le serveur de plateforme. Les opérateurs peuvent l’ajuster via la variable d’environnement `WEBDAV_MAX_PUT_BYTES`. Le corps est streamé vers une URL pré-signée Convex sans qu’un gros upload soit mis en mémoire tampon côté plateforme. - Les corps XML (PROPFIND / PROPPATCH / MKCOL / LOCK) sont plafonnés à **64 Ko** (`413` au-delà) — ces enveloppes sont minuscules par conception. - Les mots de passe applicatifs sont hachés avec HMAC-SHA256 ; le secret n’apparaît dans aucune réponse après l’appel de création. - `lastUsedAt` est patché au plus une fois par minute par mot de passe applicatif pour éviter les write-storms sur les montages actifs. ## Prérequis réseau Le point de terminaison WebDAV tourne dans le serveur Hono de la plateforme (`platform:3000` en compose). Caddy route `/dav/*` vers lui via le fallback par défaut — aucune configuration supplémentaire n’est requise. Le chemin requiert que le serveur de plateforme ait `ADMIN_KEY` défini dans son environnement pour appeler les requêtes internes Convex avec auth admin. Pour le dev (`bun dev`), le même dispatch est monté comme middleware Vite (`vite-plugins/serve-webdav.ts`) — `curl` et les clients peuvent atteindre `http://localhost:3000/dav/<orgSlug>/...` contre un serveur dev qui tourne sans rebuild. ## Sécurité WebDAV envoie le mot de passe applicatif à chaque requête sous forme de header HTTP Basic — pas de session, pas de rafraîchissement de jeton, juste l’identifiant brut rejoué à chaque PROPFIND, PUT, LOCK et ainsi de suite. Ne monte le point de terminaison que sur HTTPS ; sur HTTP en clair, le mot de passe fuite vers quiconque se trouve sur le câble, et révoquer la ligne est le seul moyen de récupérer. Ne mets jamais le mot de passe applicatif dans l’URL elle-même (la forme abrégée `https://user:pass@host/...`) — la plupart des clients consignent les URL dans l’historique du shell, les rapports de crash et les journaux d’accès du proxy, où l’identifiant survivrait bien après le démontage. Laisse le client WebDAV stocker le mot de passe dans le trousseau du système d’exploitation (macOS Keychain, Windows Credential Manager, GNOME Keyring) et le présenter via l’invite d’identifiants standard. Le serveur impose TLS au niveau du reverse proxy en production ; le mode dev sur HTTP en clair est uniquement prévu pour les tests `localhost`. Les journaux d’audit enregistrent chaque requête authentifiée avec le préfixe du mot de passe utilisé, donc un identifiant fuité peut être tracé et révoqué sans faire tourner le reste de la flotte d’appareils. ## Comment ça s’intègre WebDAV est la surface mount-protocole du même dépôt de documents que la [référence de l’API REST](/fr/develop/api-reference) anime pour l’import en lot et la recherche — les deux voies écrivent dans la table que le [Hub de documents](/fr/platform/knowledge/documents) lit, donc un fichier créé via Finder apparaît dans l’interface web sans aucune étape de synchronisation. Le protocole est le bon choix quand un utilisateur veut que ses documents se comportent comme un dossier local ; l’API REST est le bon choix quand un script ou un agent veut un contrôle au niveau de l’octet sur ce qui est écrit et quand. La RFC 4918 est l’autorité au niveau filaire pour tout ce qui se trouve sur cette page. # Page de statut Source: https://tale.dev/docs/fr/develop/status-page La page de statut est le registre canonique de la disponibilité de Tale Cloud. Chaque service rotatif a sa propre ligne de statut, l'historique des incidents est conservé pour la piste d'audit, et la page est le canal que Tale utilise pendant un incident — avant que les courriels ne partent, avant que les tickets de support ne soient répondus, la page est mise à jour. Lis ceci quand quelque chose se conduit mal et que tu veux savoir si c'est juste toi. Abonne-toi au flux quand tu es responsable de l'intégration côté toi — la page te dit quel service s'est dégradé pour que tu routes l'alerte vers la bonne équipe sans réveiller la mauvaise astreinte. ## Un abonnement mis en pratique La page de statut est à `https://status.tale.dev`. S'abonner prend une URL : ```bash curl -sS https://status.tale.dev/history.rss ``` Le flux RSS porte chaque changement d'état — ouvert, mise à jour, résolu — pour chaque service. L'abonnement par courriel est le même formulaire en un clic sur la page ; le canal courriel livre les mêmes événements avec un debounce de cinq minutes. ## Périmètre par service | Service | Ce qu'il couvre | Quand il passe au rouge | | ---------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `platform` | L'application TanStack Start + Convex — agents, workflows, intégrations, UI. | UI injoignable ; l'API renvoie 5xx ; l'auth est cassée. | | `rag` | Le service Python FastAPI de traitement de documents — indexation, récupération. | Les téléversements de documents calent ; la récupération est vide. | | `crawler` | Le service d'extraction web Crawl4AI — utilisé par l'ingestion de documents et le repli Tavily. | Les documents tirés du web échouent ; la recherche profonde cale. | | `proxy` | Le bord Caddy — terminaison TLS, routage HTTP. | Tout le trafic Tale Cloud est touché. | | `db` | TimescaleDB — état durable pour la couche Convex et les métadonnées de la plateforme. | Écritures refusées ; la ligne platform passe aussi au rouge. | Chaque ligne porte les 90 derniers jours d'uptime comme un sparkline. Un incident se lit comme une bande colorée sur la ligne ; cliquer la bande ouvre le chronogramme — première mise à jour, suites, résolution, post-mortem quand l'incident en exige un. ## Historique des incidents L'historique est conservé indéfiniment. Chaque incident enregistre les services touchés, l'énoncé d'impact client, le chronogramme, et le post-mortem quand l'incident dépasse le seuil de sévérité qui en impose un. Le seuil est publié sur la page elle-même ; la règle empirique est tout ce qui a un impact client cross-org et une durée au-dessus de 30 minutes. La page appartient à la rotation d'astreinte. Les mises à jour sont poussées par l'ingénieur qui tient la page, pas par un système automatisé — le choix est délibéré, parce que la page est aussi le document qui va aux clients et aux auditeurs après coup. ## Auto-hébergé : ce qui change Les instances auto-hébergées n'apparaissent pas sur `status.tale.dev` — cette page couvre Tale Cloud. Chaque déploiement embarque sa propre page de statut à la place, servie par la plateforme et accessible sans connexion à `https://<ton-hôte>/status`. Elle rend côté serveur un résumé de santé — operational, degraded ou outage — à partir d'une sonde de liveness contre le backend Convex, si bien qu'un opérateur (ou un utilisateur qui vérifie si le souci ne vient que de lui) peut lire la disponibilité sans se connecter. La forme lisible par machine est `https://<ton-hôte>/status.json`, qui renvoie le même résultat en JSON qu'un moniteur d'uptime peut interroger. Cette page rapporte la disponibilité du déploiement lui-même. Pour un signal d'exploitation plus fin — santé des conteneurs depuis `tale status`, métriques de requêtes depuis les journaux Caddy, et événements du plan de contrôle dans le journal d'audit du produit — la [page de dépannage observabilité](/fr/self-hosted/operate/observability/troubleshooting) associe les symptômes aux journaux. ## Où cela s'inscrit La page de statut est le canal opérationnel ; [Confiance et conformité](/fr/cloud/trust-and-compliance) est le canal d'audit et liste la page comme preuve du contrôle de disponibilité d'infrastructure. Si tu câbles Tale dans un pipeline et veux que l'intégration réagisse à une panne Tale, le flux RSS est l'entrée ; si tu lis ceci parce que quelque chose dans ton intégration échoue maintenant, la [Référence API](/fr/develop/api-reference) liste les codes d'erreur sur lesquels tu dois brancher. # Intégrations Source: https://tale.dev/docs/fr/develop/integrations Les intégrations sont les coutures entre Tale et le reste de ta stack. Le catalogue livré couvre les systèmes SaaS courants (Slack, GitHub, Microsoft 365, Google Drive, Shopify et le reste) ; quand ton système cible n'y est pas, tu construis le pont toi-même. Trois surfaces te le permettent : un connecteur REST déclaré en JSON, un adaptateur SQL pour les bases relationnelles, ou un serveur MCP quand il te faut un processus auto-hébergé pour relayer les appels. Lis ceci quand tu étends le catalogue d'intégrations. Reviens-y quand une operation que tu as déclarée n'apparaît pas dans la barre d'outils de l'agent — la réponse est presque toujours un conflit de schéma contre la référence sous `.tale/reference/integrations/`. ## Un connecteur REST personnalisé mis en pratique L'intégration utile la plus simple est une seule operation REST déclarée en JSON. Dépose un dossier dans le projet et l'intégration apparaît sous **Paramètres > Intégrations** sans changement de code : ```text integrations/ acme-billing/ config.json connector.ts # optionnel, pour façonner les requêtes non triviales icon.svg ``` `config.json` déclare la méthode d'auth, les hôtes autorisés et les operations : ```json { "slug": "acme-billing", "name": "ACME Billing", "auth": { "type": "apiKey", "header": "X-API-Key" }, "allowedHosts": ["api.acme.example.com"], "operations": [ { "name": "list_invoices", "method": "GET", "path": "/v1/invoices", "query": { "since": "string?" } } ] } ``` L'operation apparaît sur les agents comme une famille de tools dès que l'org branche ses identifiants. Le fichier connecteur est optionnel — sers-t'en quand la forme de réponse a besoin d'être aplatie ou quand la pagination demande des boucles que le manifeste ne peut pas exprimer. Pour un connecteur OAuth2 (`"auth": { "type": "oauth2", … }`), enregistre l'URL de callback de Tale comme URI de redirection autorisée dans l'app OAuth upstream, sinon l'étape de consentement échoue avec un `redirect_uri` non concordant. Le callback est `${SITE_URL}/api/integrations/oauth2/callback` (préfixé par `BASE_PATH` s'il est défini). En développement local, cet origin est ton URL de dev — `http://localhost:3000/api/integrations/oauth2/callback`, pas un hôte `https://`. ## Choix de la surface | Surface | Sers-t'en quand | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Manifeste REST | Le système cible parle JSON sur HTTPS et l'auth est clé API ou OAuth2. Couvre la plupart des API SaaS. | | Adaptateur SQL | La cible est une base relationnelle (Postgres, MySQL, SQL Server) et tu veux que les agents lisent des tables sous policy par ligne. | | Serveur MCP | Le pont doit être un processus de longue durée — fichiers locaux, une CLI à toi, un système inatteignable depuis le réseau de Tale. | | Connecteur TS | Le manifeste REST couvre 80 % de l'API mais une operation a besoin d'une mise en forme que le manifeste ne sait pas déclarer. | Les intégrations livrées sous [Platform > Intégrations](/fr/platform/integrations/overview) sont le catalogue des manifestes REST que Tale livre — lis leurs configs dans `builtin-configs/integrations/` pour les motifs que tu copieras. ## Adaptateurs SQL Un adaptateur SQL expose une surface de tools façon Tale sur une base SQL. Tu déclares la connexion (driver, hôte, référence d'identifiant) et les tables que l'intégration a le droit de lire ; l'adaptateur génère une operation `query_<table>` par table déclarée et une operation `run_named_query` pour les requêtes que tu autorises par nom. Les écritures passent par les mutations déclarées uniquement — il n'y a pas d'operation `execute` brute. L'autorisation ligne par ligne est la responsabilité de l'opérateur : déclare une colonne tenant sur chaque table et Tale injectera le filtre tenant dans chaque requête générée. Les operations qui touchent une table sans colonne tenant échouent à la validation au déploiement. ## Serveurs MCP Quand l'intégration ne peut pas s'exprimer comme un manifeste JSON — une CLI, une chaîne d'outils locale, n'importe quoi isolé du réseau de Tale — écris un serveur MCP et enregistre-le sous **Paramètres > Serveurs MCP**. Chaque tool que le serveur expose apparaît dans la barre d'outils de l'agent avec approbation par tool au premier appel. Le transport est stdio pour Tale auto-hébergé ; pour Tale Cloud, le serveur vit sur ton réseau et Tale l'appelle via un tunnel HTTPS signé. Le walk-through MCP complet vit sous [Serveur MCP de zéro](/fr/tutorials/developer/mcp-server-from-scratch) — cette page est la construction ; celle-ci est le choix. ## Où cela s'inscrit Les intégrations personnalisées sont la manière dont Tale atteint des systèmes que le catalogue livré ne couvre pas. La [vue d'ensemble des intégrations](/fr/platform/integrations/overview) liste ce qui est déjà là ; une fois ton intégration personnalisée déclarée, [Tools d'agent](/fr/platform/agents/tools) explique comment ses operations apparaissent sur un agent. Si le pont doit vivre entièrement hors de Tale — un processus que tu démarres, un hôte que tu contrôles — la [référence Serveurs MCP](/fr/platform/integrations/mcp-servers) couvre l'autre moitié. # Webhooks Source: https://tale.dev/docs/fr/develop/webhooks Les webhooks sont la manière dont Tale et le reste de ta stack se parlent en asynchrone. Deux directions existent : entrant — ton système POST sur un déclencheur de workflow Tale pour tirer une exécution — et sortant — Tale POST sur ton URL quand quelque chose qui l'intéresse arrive. Les deux moitiés partagent la même politique de retraitement (backoff exponentiel avec jitter) mais s'authentifient différemment : les requêtes entrantes portent leur justificatif comme jeton dans l'URL, les livraisons sortantes sont signées en HMAC-SHA256 sur le body. Lis ceci quand tu câbles une intégration qui doit réagir à des événements dans une des directions. Reviens-y quand un webhook tire mais que le récepteur ne le voit pas, ou quand les retries ne se comportent pas comme tu l'attendais. ## Un webhook sortant mis en pratique Quand un événement que Tale surveille survient — une exécution de workflow se termine, un agent finit une réponse, une écriture de document s'achève — Tale POST l'événement sur ton URL configurée : ```http POST https://your-host.example.com/webhooks/tale Content-Type: application/json X-Tale-Event: workflow.execution.completed X-Tale-Signature: sha256=<hex> X-Tale-Delivery: <uuid> X-Tale-Timestamp: 1717000000 { "event": "workflow.execution.completed", "data": { "workflowId": "...", "executionId": "...", "status": "succeeded", ... } } ``` Vérifie la signature avant de faire confiance au body : HMAC-SHA256 sur le body brut avec le secret par endpoint, encodé en hex. Compare en temps constant. Rejette toute requête plus vieille que cinq minutes en comparant `X-Tale-Timestamp` à ton horloge. ## Un déclencheur entrant mis en pratique Quand ton système doit tirer un workflow Tale, POST sur l'URL de webhook que Tale émet quand tu ajoutes un déclencheur webhook au workflow : ```bash curl -sS https://your-host.example.com/api/workflows/wh/<token> \ -H "Idempotency-Key: order-12345" \ -H "Content-Type: application/json" \ -d '{ "orderId": "12345", "amount": 199.0 }' ``` Le jeton dans le chemin de l'URL est le justificatif — aucun en-tête Authorization n'est requis ; traite donc l'URL entière comme un secret et supprime le webhook pour le révoquer. Le body devient l'entrée de la première étape du workflow. Une première acceptation renvoie `{ "status": "accepted", "workflowSlug": "..." }` ; un rejeu avec la même `Idempotency-Key` renvoie l'`executionId` de l'exécution d'origine au lieu d'en lancer une nouvelle. ## Signer et vérifier Sortant : le secret de signature par endpoint est affiché une fois quand tu ajoutes l'endpoint sous **Paramètres > Intégrations** ou dans le panneau de déclencheur webhook de l'éditeur de workflow. Tale signe chaque body en HMAC-SHA256 avec ce secret ; la vérification est une comparaison de chaînes en temps constant. Entrant : il n'y a pas de signature — le jeton dans l'URL est l'auth. Si tu ne peux pas garder l'URL secrète, ne la distribue pas ; supprime le webhook pour la faire tourner. ```python import hmac, hashlib def verify(body: bytes, signature: str, secret: str) -> bool: expected = "sha256=" + hmac.new( secret.encode(), body, hashlib.sha256, ).hexdigest() return hmac.compare_digest(expected, signature) ``` ## Idempotence Entrant : passe `Idempotency-Key` à chaque appel de déclencheur. Tale stocke la clé contre l'exécution résultante pendant 24 heures ; un retry avec la même clé renvoie le même ID d'exécution sans retirer le workflow. Sortant : chaque livraison porte un UUID `X-Tale-Delivery` unique. Utilise-le pour dédupliquer de ton côté — Tale retraite sur les réponses non-2xx, et le même UUID de livraison apparaîtra à chaque retry jusqu'à ce que le récepteur acquitte. ## Retraitements Les retraitements sortants suivent un backoff exponentiel avec jitter, plafonnés à 24 heures de tentatives. Le calendrier : - Retry immédiat sur un 5xx ou un timeout. - 30 s, 1 m, 5 m, 30 m, 2 h, 8 h, 24 h après le premier échec. - Après 24 h sans 2xx, la livraison est marquée comme échouée ; le journal d'audit l'enregistre. Les retraitements entrants sont la responsabilité de l'appelant — la réponse de Tale indique le succès ou l'échec du déclencheur, pas des étapes du workflow. Si tu veux retraiter, utilise une clé d'idempotence stable. ## Où cela s'inscrit Les webhooks sont la couture entre Tale et les systèmes externes des deux côtés. La [référence API](/fr/develop/api-reference) couvre la moitié synchrone — les endpoints que tu appelles quand tu veux une valeur en retour immédiate. La [référence Déclencheurs](/fr/platform/automations/triggers) couvre le côté workflow des webhooks entrants — la configuration qui transforme un POST en une exécution de workflow. # Développement assisté par IA Source: https://tale.dev/docs/fr/develop/ai-assisted-development Les projets Tale sont du JSON — agents, workflows, integrations, branding — et le JSON s'édite bien dans les éditeurs IA quand l'éditeur connaît le schéma. La CLI pose deux choses pour cela : un fichier de règles que chaque éditeur lit à la racine du projet (`CLAUDE.md` pour Claude Code, `.cursor/rules/tale.mdc` pour Cursor, `.github/copilot-instructions.md` pour Copilot, `.windsurfrules` pour Windsurf), et un miroir de schéma en lecture seule sous `.tale/reference/` vers lequel le fichier de règles pointe l'éditeur. Lis ceci quand tu veux éditer un projet Tale dans un éditeur IA sans taper le JSON à la main. Reviens-y quand l'éditeur invente des champs ou câble la mauvaise forme d'agent — la réponse est presque toujours que le schéma sous `.tale/reference/` est périmé. ## Une mise en place mise en pratique Initialise un projet — la CLI écrit le fichier de règles et le miroir de schéma dans la même étape : ```bash tale init my-org cd my-org ls -a # .cursor/ .github/ .tale/ .windsurfrules # CLAUDE.md agents/ workflows/ integrations/ branding/ ``` `CLAUDE.md` (installé en même temps comme `.mdc` Cursor, `.md` Copilot et fichier de règles Windsurf) dit à l'éditeur où regarder avant d'éditer une config : > Before creating or editing any config, read the relevant schemas and implementation code in `.tale/reference/` to understand the valid structure, fields, and constraints. Use existing config files in the project as examples. La directive compte parce que tout éditeur sous charge saute les lectures de schéma sauf instruction contraire. Le fichier de règles est le contrat ; le miroir de schéma est la vérité du terrain. ## Ce qui vit où | Chemin | Ce que c'est | | ---------------------------------- | ------------------------------------------------------------------------------------ | | `agents/` | Un fichier JSON par agent — instructions, connaissances, tools, modèle. | | `workflows/` | Configs JSON de workflow, groupées par sous-répertoire de catégorie. | | `integrations/<slug>/config.json` | Manifeste d'intégration — operations, méthode d'auth, hôtes autorisés. | | `integrations/<slug>/connector.ts` | Connecteur TypeScript optionnel pour les formes REST que le manifeste ne couvre pas. | | `branding/branding.json` | Branding de l'org — couleurs, logos, expéditeurs courriel. | | `.tale/reference/` | Miroir de schéma en lecture seule ; régénéré par `tale init` et `tale update`. | L'arbre de référence est byte-à-byte identique aux schémas contre lesquels la plateforme valide au déploiement. Traite-le comme canonique : quand un nom de champ dans une config écrite à la main désaccorde avec la référence, la référence gagne. ## Travailler avec l'éditeur Le fichier de règles nomme trois règles que chaque éditeur applique pendant l'édition : - **Les agents lient, délèguent, attachent.** Un agent peut simultanément lier des intégrations (`integrationBindings`), déléguer à d'autres agents (`delegates`) et attacher des workflows (`workflows`). Lis les configs existantes avant d'introduire une nouvelle liaison. - **Les workflows utilisent les operations d'intégration.** Une étape de workflow référence une operation d'intégration déclarée dans `integrations/<slug>/config.json`. Éditer une étape contre une operation qui n'existe pas fait échouer la validation. - **Le nommage est imposé.** Les noms de fichier d'agent correspondent à `[a-z0-9][a-z0-9_-]*\.json`. Les slugs d'étape de workflow correspondent à `[a-z0-9][a-z0-9_-]*`. Les répertoires d'intégration sont en minuscules alphanumériques avec tirets ou soulignés. Quand l'éditeur propose un changement, demande-lui de citer le fichier dans `.tale/reference/` sur lequel il s'est appuyé. S'il ne peut pas, régénère le miroir avec `tale update` et réessaie. ## Cursor : plan config vs plan runtime Cursor apparaît dans Tale à deux endroits distincts — ne les confonds pas. | Plan | Rôle | Où ça vit | | ----------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | **Config** | Aide Cursor (ou tout éditeur IA) à éditer le JSON d'un projet Tale sur ta machine | `.cursor/rules/tale.mdc`, `CLAUDE.md`, `.tale/reference/` — tout ce que `tale init` écrit | | **Runtime** | Lance la CLI Cursor Agent en mode headless dans un bac à sable isolé quand tu discutes avec l'agent externe **Cursor** intégré | Sélecteur de chat → **Cursor** ; JSON d'agent avec `primaryBehavior: "external-agent"` et `agentKind: "cursor"` | Le fichier de règles et le miroir de schéma sur cette page sont le **plan config** : ils guident un éditeur local pendant que tu modifies agents, workflows et intégrations. Le **plan runtime**, c'est un tour de bac à sable géré — `agent -p --output-format stream-json` avec ta `CURSOR_API_KEY`, progression normalisée dans le chat et reprise de session entre les relances. Credentials, modèles et facturation des tours runtime sont dans [External agents](/fr/platform/agents/external-agent), pas ici. ## Où cela s'inscrit Le développement assisté par IA est le chemin d'édition ; le déploiement est le chemin de publication. Une fois qu'une config passe la validation de l'éditeur, [`tale deploy`](/fr/self-hosted/install/cli-install) la rapproche de la plateforme — le même contrôle de schéma, cette fois comme barrière. Pour les fonctionnalités que l'éditeur n'atteint pas (le constructeur dans le produit, l'éditeur visuel de workflow), l'[onglet Platform](/fr/platform) est la surface canonique ; le chemin éditeur IA ici est pour les projets qui préfèrent la config-as-code. # Configuration contributeur Source: https://tale.dev/docs/fr/develop/contributor-setup Cette page est pour les contributeurs qui veulent faire tourner Tale depuis le code source et renvoyer une modification. Elle couvre les prérequis, la mise en place unique, la vérification pré-vol qui détecte une machine cassée avant un long démarrage, et ce que tu peux attendre de `bun run dev`. Ce n'est pas le chemin de l'opérateur — si tu veux faire tourner Tale pour l'utiliser, pas le modifier, le [démarrage rapide auto-hébergé](/fr/self-hosted/install/quickstart) installe la stack empaquetée avec la CLI à la place. Le code source est un seul workspace Bun, de bout en bout — toute la stack est TypeScript, sans Python ni second gestionnaire de paquets à installer. Un seul `bun install` câble chaque service, et `bun run dev` démarre la plateforme avec un backend Convex local, des secrets de dev générés et Vite — pas de compte cloud, pas de `.env` édité à la main. Le travail de connaissances qui vivait autrefois dans des services autonomes (recherche RAG, ingestion de documents, crawling web, génération de documents) tourne désormais dans le backend Convex, donc il n'y a rien de plus à démarrer pour lui. ## Une configuration qui marche, de bout en bout Le chemin le plus court d'un clone neuf à une app qui tourne fait quatre commandes. La vérification pré-vol entre install et dev est celle qui t'épargne un échec déroutant dix couches en profondeur : ```bash bun install # câbler chaque workspace bun run setup:check # valider Bun, les ports de dev et la CLI Convex bun run dev # démarrer Convex + Vite (guette la bannière READY) ``` Si `setup:check` affiche tout en vert et que `bun run dev` atteint sa bannière `READY`, ton environnement est sain. Le reste de cette page explique chaque pièce et quoi faire quand l'une d'elles se plaint. ## Prérequis Un seul outil doit être sur ton `PATH` avant tout le reste, parce que toute la stack est du TypeScript sur une seule runtime : - **Bun 1.3 ou plus** — la runtime de workspace et le gestionnaire de paquets. Installe-le depuis [bun.sh](https://bun.sh/docs/installation), puis confirme avec `bun --version`. Tout le reste dont le code source a besoin (la CLI Convex, chaque dépendance de service) est résolu par `bun install`. Tu n'as pas besoin de Docker pour le développement local avec `bun run dev` — il lance Convex directement sur ta machine. Docker n'entre en jeu que pour le mode hybride conteneurisé plus bas et pour l'installation de l'opérateur. ## Installation et pré-vol Une seule installation couvre chaque workspace, parce que le dépôt est un graphe de workspaces Bun unique : ```bash bun install ``` Avant le premier `bun run dev`, lance la vérification pré-vol. Elle valide ta version de Bun, que les ports 3000 et 3210 sont libres et que la CLI Convex est joignable — et imprime la correction exacte pour tout ce qui manque, pour que tu ne découvres pas une mauvaise version de Bun à mi-chemin d'un démarrage à froid : ```bash bun run setup:check ``` Chaque ligne en échec porte sa correction : un `bun upgrade` pour un vieux Bun, une paire `lsof`/`kill` pour un port occupé. Un passage propre se termine à zéro et te dit d'avancer avec `bun run dev`. ## Ce que fait `bun run dev` `bun run dev` est l'orchestrateur de développement. Il charge tes fichiers `.env`, génère des valeurs par défaut locales non sécurisées pour chaque secret que tu n'as pas réglé, lance un backend Convex local en mode anonyme, y synchronise l'environnement, exécute le codegen Convex, attend que les routes d'auth répondent, puis démarre Vite. La plateforme est le serveur le plus lent à monter parce qu'elle attend Convex, donc un démarrage à froid prend de 30 à 90 secondes. Tant que l'orchestrateur n'imprime pas sa bannière `READY`, le fait que l'app refuse les connexions sur `http://localhost:3000` est attendu, pas un échec — Vite n'a pas encore lié le port. Quand tu vois la bannière, l'app est joignable et l'auth est saine. Arrête toute la stack avec `Ctrl-C` ; elle ferme proprement Convex et Vite. L'orchestrateur de dev génère tout ce dont il a besoin, donc une copie locale de `.env.example` est optionnelle pour le développement local — les valeurs par défaut non sécurisées (`INSTANCE_SECRET`, `BETTER_AUTH_SECRET`, la clé HMAC WebDAV) sont remplies au démarrage et imprimées comme avertissements. Règle de vraies valeurs dans `services/platform/.env.local` seulement quand tu as besoin d'un comportement façonné pour la production ou veux surcharger une valeur par défaut. ## Quand un port est occupé `bun run dev` lie deux ports : 3000 pour l'app Vite et 3210 pour le backend Convex local. Il échoue tout de suite avec un message actionnable quand l'un est pris, parce qu'un repli silencieux vers un autre port casserait le proxy Convex et chaque lien `localhost:3000`. Le coupable habituel est un `bun run dev` ou `tale dev` précédent qui n'a pas complètement quitté. Libère le port et relance. La commande qui trouve et arrête le détenteur est celle que `setup:check` et l'orchestrateur suggèrent : ```bash lsof -nP -iTCP:3000 -sTCP:LISTEN # montrer la PID qui tient le port de l'app kill <PID> # l'arrêter ``` Pour faire tourner l'app sur un autre port à la place, règle `PORT` : `PORT=3005 bun run dev`. Si le déploiement Convex reste dans un mauvais état après la maintenance automatique — schéma périmé après migration avortée, SQLite locale corrompue — voir [Réinitialiser les données Convex de dev locales](#réinitialiser-les-données-convex-de-dev-locales) ci-dessous ; ne supprime pas `.convex/local/` à la légère. ## Maintenance du stockage Convex local Chaque push `convex dev` stocke un nouveau bundle de fonctions sous `services/platform/.convex/local/default/convex_local_storage/modules/`. La CLI Convex ne garbage-collecte jamais les anciens blobs en local — des mois de dev quotidien peuvent accumuler des dizaines de milliers de fichiers (10+ Go) et faire échouer les cold starts dans la fenêtre de 30 secondes de la CLI. `bun run dev` lance la maintenance automatiquement avant de spawner Convex : - **Prune** quand le stockage modules dépasse 1 500 blobs ou 2 Go — ne supprime que les blobs historiques non référencés sous `convex_local_storage/modules/`, en gardant chaque blob que le déploiement actuel charge encore (packages source des modules et leurs parents deps node via `externalPackageId`, plus jusqu'à 1 000 restes non référencés les plus récents). La base SQLite, les fichiers uploadés et la config org restent intacts. Si les références live ne peuvent pas être lues, ou semblent vides alors que des blobs restent sur disque, le prune est ignoré plutôt que de deviner. - **Contrôle d'intégrité** — si un blob de module live manque déjà sur disque, `bun run dev` s'arrête avec une erreur claire qui pointe vers `setup:clean`. Continuer démarrerait un backend à moitié mort (chat et crons échouent avec des erreurs serveur opaques). - **Supprime les artefacts d'export snapshot** quand la version binaire Convex en cache ne correspond plus à celle enregistrée dans le déploiement local — retire `export.zip` et les restes d'import/export qui peuvent déclencher un ré-import raté au cold start, sans effacer les données de dev. Règle `TALE_DEV_SKIP_CONVEX_MAINTENANCE=1` pour désactiver le prune/nettoyage snapshot (le contrôle d'intégrité tourne quand même). `bun run setup:check` avertit (sans bloquer) quand le stockage modules dépasse déjà le seuil de prune. ## Réinitialiser les données Convex de dev locales En dernier recours seulement — `bun run setup:clean` efface **toutes** les données Convex de dev locales : chaque table du SQLite local, chaque upload dans `convex_local_storage/files/`, chaque bundle de fonctions. La config org sur disque et `.env.local` restent intacts. **Garde tes données à travers le reset.** Même quand la barrière d'intégrité se déclenche (le bundle d'un module actif manque), le backend lui-même démarre encore — tu peux donc exporter tes données avant et les restaurer après, et le reset ne perd alors rien : ```bash # 1. Démarre le backend (cela contourne la barrière d'intégrité de # `bun run dev`), puis exporte dans un second terminal : bun run --filter @tale/platform convex:dev cd services/platform && npx convex export --path convex-backup.zip # 2. Réinitialise (protégé — voir ci-dessous), bootstrappe un déploiement # neuf, puis restaure : bun run setup:clean # tape : delete local convex bun run dev # attends la bannière READY cd services/platform && npx convex import --replace-all convex-backup.zip ``` `bun run setup:clean` est volontairement protégé (les agents de code ne doivent pas l'exécuter sauf demande explicite de ta part) : 1. Lance-le toi-même dans un terminal — pas via un agent. 2. Au prompt, tape la phrase exacte `delete local convex` (un simple `y` est refusé). 3. Les exécutions non interactives (CI) exigent `TALE_CONFIRM_DESTROY_LOCAL_CONVEX=delete-local-convex` — ne jamais le définir dans les shells d'agents. Essaie d'abord la maintenance automatique et un `bun run dev` normal. S'il faut vraiment réinitialiser, **exporte d'abord** (ci-dessus) pour garder tes données — ne saute l'export que si tu n'as réellement pas besoin des conversations locales, des uploads et du reste de l'état du déploiement anonyme. ## Mode hybride contre un Convex conteneurisé `bun run dev` lance par défaut un backend Convex éphémère, ce qui est la bonne chose pour l'essentiel du travail. Quand tu veux des reloads Vite rapides contre un Convex stable qui reflète la production, fais tourner le conteneur `convex` dédié et pointe Vite vers lui à la place : ```bash docker compose up convex # un terminal : le backend stable CONVEX_EXTERNAL=true bun run dev # un autre : Vite contre le conteneur ``` Règle `CONVEX_URL` si ton conteneur expose Convex sur un hôte ou un port non standard. C'est le seul chemin de dev local qui a besoin de Docker, et il est optionnel — le backend éphémère par défaut n'a besoin de rien au-delà des trois prérequis. ## Avant d'ouvrir une PR Chaque PR passe par un gate : `bun run check`, c'est-à-dire format, lint, typecheck et la suite de tests complète sur chaque workspace touché. Un passage vert est le signal de merge ; un rouge bloque. La checklist pré-PR dans [`AGENTS.md`](https://github.com/tale-project/tale/blob/main/AGENTS.md) liste le reste — la doc et les traductions arrivent dans la même PR que le code qui les a modifiées. Si ta modification touche `services/docs/`, lance aussi le gate de la doc (`bun run --filter @tale/docs test`) pour que la parité structurelle, la terminologie et les vérifications de prose passent avant la revue. Tout ce qu'un utilisateur peut voir, configurer ou appeler a besoin de sa doc mise à jour dans les trois locales de base dans le même commit. ## Où cela s'inscrit La configuration contributeur est le sol sur lequel se tient chaque autre tâche de développeur : mets les prérequis en place, laisse `setup:check` confirmer la machine, et `bun run dev` te donne toute la plateforme avec un backend local en moins de deux minutes une fois les images chaudes. La vérification pré-vol et la correction de port existent parce que les échecs de premier passage les plus courants sont une mauvaise version d'outil ou un processus résiduel qui tient un port — deux corrections de cinq secondes une fois que tu peux les voir. Une fois la stack en marche, l'[aperçu Développement](/fr/develop/overview) cadre la surface externe contre laquelle tu construis, et [Développement assisté par IA](/fr/develop/ai-assisted-development) couvre l'usage des agents Tale pour écrire des configurations Tale. Si tu contribues une modification de conteneur plutôt qu'une modification de code source, [Contribuer](/fr/self-hosted/contributing-docker) sous l'onglet Auto-hébergé est le parcours build-and-test pour ce chemin. # Démarrage rapide Source: https://tale.dev/docs/fr/get-started/quickstart C’est le chemin le plus court vers un chat qui répond : obtenir une instance, se connecter, envoyer un message, regarder la réponse arriver en streaming. Compte environ cinq minutes sur une instance prête et quinze sur ta propre machine ; à la fin tu vois l’écran ci-dessous — une vraie réponse d’un agent sur ton espace de travail. <Frame caption="Là où ce démarrage rapide se termine : une réponse d’agent en streaming dans l’onglet Chat."> ![Un fil de chat montrant une question d’utilisateur sur des retours d’onboarding et une réponse de l’assistant contenant un tableau markdown de trois thèmes.](/images/platform/chat-thread-reply.webp) </Frame> ## Obtenir une instance Les deux éditions font tourner le même produit — choisis selon qui doit exploiter la stack. <Tabs> <Tab title="Auto-hébergé"> Avec [Docker](https://www.docker.com/products/docker-desktop) en marche, trois commandes montent toute la stack sur ta machine : ```bash curl -fsSL https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.sh | bash tale init my-project && cd my-project tale dev ``` Le premier lancement récupère les images — compte cinq à dix minutes. Quand le navigateur s’ouvre, inscris-toi : le premier compte revendique le rôle **Propriétaire** et crée ton organisation. Le [démarrage rapide auto-hébergé](/fr/self-hosted/install/quickstart) couvre chaque étape en profondeur, Windows et dépannage compris. </Tab> <Tab title="Cloud"> Les instances Cloud sont montées pour toi : remplis le [formulaire de demande de démo](https://tale.dev/fr/request-demo) et l’équipe Tale provisionne ta propre instance. Une fois qu’elle est prête, ouvre-la et inscris-toi — le formulaire demande ton nom, ton e-mail et un mot de passe ; vérifie le lien reçu par e-mail, nomme ton organisation et tu atterris dans le dashboard. L’assistant de configuration propose de connecter un fournisseur d’IA tout de suite — colle une clé [OpenRouter](https://openrouter.ai) à cet endroit et le chat fonctionne immédiatement. Le [parcours admin](/fr/get-started/admins) déroule le même assistant, captures d’écran à l’appui, quand tu veux plus que le chemin le plus direct. </Tab> </Tabs> ## Envoyer ton premier message <Steps> <Step title="Ouvre un nouveau chat"> Clique sur **Nouveau chat** dans la barre latérale. Le composeur en bas de l’écran est le point de départ de tout : le sélecteur d’agent à gauche, le sélecteur de modèle à côté, et le champ de message avec l’envoi à droite. Le composeur qui attend avec **Assistant** et **Auto** présélectionnés signifie que tu es prêt à envoyer. <Frame caption="Le composeur — le champ de message en haut, les sélecteurs d’agent et de modèle et l’envoi en dessous."> ![Le composeur de chat vide, dont le texte d’invite propose de poser une question sur les contacts, les produits ou les documents, au-dessus d’une barre d’outils qui porte les boutons de pièce jointe et de bibliothèque de prompts, les sélecteurs d’agent et de modèle, et les boutons de sourdine, de micro et d’envoi.](/images/platform/chat-composer.webp) </Frame> </Step> <Step title="Pose une vraie question"> Laisse l’agent sur **Assistant** et le modèle sur **Auto** — Tale résout le meilleur modèle disponible au moment de la requête. Tape une question et envoie-la. La réponse arrive en streaming, token par token ; quand l’agent raisonne avant de répondre, une ligne de réflexion repliable apparaît au-dessus de la réponse. <Check> Une réponse en streaming qui répond à ta question prouve que toute la chaîne fonctionne — fournisseur, routage de modèle et agent. Tu as un espace de travail opérationnel. </Check> </Step> </Steps> ## Où tu en es Tu as une instance qui tourne et un agent qui répond. Les quinze prochaines minutes dépendent de ton rôle : le [parcours membre](/fr/get-started/members) couvre les documents et les projets, le [parcours éditeur](/fr/get-started/editors) publie ton premier agent spécialiste, le [parcours admin](/fr/get-started/admins) monte l’équipe et les fournisseurs, et le [parcours développeur](/fr/get-started/developers) te donne une clé API et ta première requête. # Ton premier jour d’administration Source: https://tale.dev/docs/fr/get-started/admins Ce parcours s’adresse à la personne responsable de l’espace de travail. En quinze minutes, tu crées l’organisation, tu connectes le fournisseur qui fait répondre le chat, tu fais entrer tes premiers collègues et tu apprends où vivent les contrôles de gouvernance avant d’en avoir besoin. Il te faut un compte sur une instance qui tourne ([démarrage rapide](/fr/get-started/quickstart)) ; sur une instance toute neuve, le premier compte est automatiquement **Propriétaire**, ce qui porte toutes les permissions ci-dessous. <Steps> <Step title="Crée l’espace de travail"> Si tu arrives du démarrage rapide, ton organisation existe déjà — passe directement à la connexion d’un fournisseur. Une première connexion sans organisation atterrit sur l’assistant de création : le **Nom de l'organisation** est le nom affiché que ton équipe voit dans le coin de chaque page — choisis-en un qui survit à un rebranding. L’assistant propose ensuite de connecter un fournisseur d’IA et se termine sur le dashboard. <Frame caption="L’étape espace de travail de l’assistant de création."> ![L’assistant de création d’organisation à son étape espace de travail, avec Northlight Labs saisi dans le champ Nom de l’organisation et le bouton Suivant actif.](/images/get-started/org-create-wizard.webp) </Frame> </Step> <Step title="Connecte un fournisseur d’IA"> Rien ne répond tant qu’aucun fournisseur n’est connecté. Si tu as sauté l’étape fournisseur de l’assistant, ouvre **Paramètres > Fournisseurs IA** et clique sur **Ajouter un fournisseur** — colle une clé [OpenRouter](https://openrouter.ai) pour le catalogue de modèles le plus large, ou n’importe quel fournisseur compatible OpenAI. Une confirmation sur la ligne du fournisseur signifie que la clé est valide ; à partir de ce moment, chaque agent de l’espace de travail peut répondre. <Frame caption="Un fournisseur connecté avec son catalogue de modèles."> ![La page des paramètres des fournisseurs d’IA listant un seul fournisseur connecté, OpenRouter, avec son URL de base et ses 52 modèles.](/images/get-started/settings-providers.webp) </Frame> </Step> <Step title="Fais entrer l’équipe"> Pour ajouter des personnes, ouvre **Paramètres > Organisation**, descends jusqu’à la section **Membres** et clique sur **Ajouter un membre**. Chaque personne arrive avec un rôle qui borne ce qu’elle peut faire : **Membre** lit et discute, **Éditeur** construit agents et connaissances, **Développeur** câble workflows, automatisations et accès API, **Admin** gère l’espace de travail. Commence bas — monter un rôle plus tard prend un clic, et reprendre un accès qui a fuité, non. <Frame caption="La section Membres — chaque compte et son rôle."> ![La page des paramètres de l’organisation avec sa section Membres listant le propriétaire de l’espace de travail Alex Rivera et un bouton Ajouter un membre.](/images/get-started/settings-organization-members.webp) </Frame> <Check> Un collègue qui se connecte et obtient une réponse dans le chat prouve toute la chaîne — compte, rôle, fournisseur — sans que tu sois à côté de lui. </Check> </Step> <Step title="Sache où vit la gouvernance"> Tu n’auras pas besoin de politiques le premier jour, mais tu dois connaître la porte : **Paramètres > Gouvernance** regroupe journaux d’audit, analyses d’usage, politiques de contenu, garde-fous et rétention. La seule habitude qui vaut d’être prise aujourd’hui est de parcourir les [journaux d’audit](/fr/platform/admin/governance/audit-logs) après la première semaine — ils montrent ce que ton espace de travail fait vraiment. </Step> </Steps> ## Où tu en es L’espace de travail tient debout : un fournisseur répond, l’équipe est entrée avec des rôles bornés et tu sais où vivent les contrôles. La matrice complète des permissions est [Membres et rôles](/fr/platform/admin/members-and-roles) ; la [vue d’ensemble admin](/fr/platform/admin/overview) cartographie chaque panneau que tu possèdes désormais ; et quand la conformité te sollicite, la [gouvernance](/fr/platform/admin/governance/audit-logs) est la section à lui montrer. # Ton premier jour de création d’agents Source: https://tale.dev/docs/fr/get-started/editors Ce parcours s’adresse à la personne qui transforme « l’équipe pose toujours les mêmes questions » en un agent qui y répond. En quinze minutes, tu crées un agent, tu façonnes son comportement et tu le regardes répondre dans le chat — la boucle que chaque agent suivant raffine. Il te faut le rôle **Éditeur** ou plus (la section Agents est masquée pour les membres) sur un espace de travail où le chat répond déjà — c’est le [démarrage rapide](/fr/get-started/quickstart). <Steps> <Step title="Crée l’agent"> Pour lancer un agent que tes collègues peuvent choisir dans le chat, ouvre **Agents** dans la barre latérale et clique sur **Créer un agent**. Nomme-le d’après le travail, pas la technologie — « Tri support » bat « GPT Helper » — parce que ce nom est ce que tes collègues choisiront plus tard dans le composeur du chat. </Step> <Step title="Façonne son identité"> L’éditeur s’ouvre sur l’onglet **Général** : le nom affiché que voient tes collègues, une description d’une ligne et le type d’agent. L’interrupteur qui compte au premier jour est **Visible dans le chat** — sans lui, l’agent existe mais personne ne peut le choisir depuis le composeur. <Frame caption="L’onglet Général — identité, type d’agent et visibilité dans le chat."> ![L’onglet Général de l’éditeur d’agent pour l’agent Assistant, montrant les options de type d’agent, l’interrupteur Visible dans le chat et le champ du nom affiché.](/images/get-started/agent-editor-general.webp) </Frame> </Step> <Step title="Écris les instructions"> Ouvre **Instructions et modèles** — le levier qui compte le plus. Écris un paragraphe comme si tu briefais un nouveau collègue : la voix dans laquelle répondre, le domaine qu’il possède et les cas qu’il doit refuser. Concret bat complet — tu affineras après avoir vu de vraies réponses. <Frame caption="Instructions et modèles — le prompt système au-dessus de la liste ordonnée de modèles."> ![L’onglet Instructions et modèles de l’éditeur d’agent montrant le champ du prompt système et la liste ordonnée de modèles pour l’agent Assistant.](/images/platform/agent-editor-instructions.webp) </Frame> </Step> <Step title="Lie le modèle"> Le même onglet lie le modèle : choisis-en un parmi les fournisseurs configurés de l’espace de travail, ou laisse le routage en automatique pour que Tale résolve le meilleur modèle disponible à chaque requête. Clique sur **Enregistrer** — un toast **Agent enregistré** confirme l’écriture. </Step> <Step title="Regarde-le répondre"> Ouvre **Nouveau chat**, choisis ton agent dans le sélecteur d’agent et pose une question en plein dans les instructions que tu as écrites. Puis pose une question que les instructions disent de refuser. <Frame caption="Le sélecteur d’agent — ton nouvel agent listé à côté des agents du catalogue."> ![Le sélecteur d’agent du composeur de chat ouvert, listant les agents disponibles dans l’espace de travail.](/images/platform/chat-agent-picker.webp) </Frame> <Check> Une réponse dans la bonne voix au premier message et un refus au second prouvent que les instructions tiennent — l’agent est réel. </Check> </Step> </Steps> ## Où tu en es Tu as livré le plus petit agent réel : des instructions, un modèle, une place dans le sélecteur. Le modèle complet derrière ce que tu viens de toucher est [Concepts d’agent](/fr/platform/agents/concepts) — instructions, connaissances, outils et modèle comme quatre leviers. La construction suivante naturelle est [ton premier agent de bout en bout](/fr/tutorials/editor/first-agent-end-to-end), qui ajoute des liaisons de connaissances et un vrai domaine ; ensuite, [agents avec connaissances](/fr/tutorials/editor/agent-with-knowledge) et [délégation entre agents](/fr/tutorials/editor/delegate-between-agents) poussent la même boucle plus loin. # Ton premier jour avec Tale Source: https://tale.dev/docs/fr/get-started/members Ce parcours s’adresse à tous ceux qui utilisent Tale sans le configurer. En quinze minutes, tu discutes avec un agent, tu ajoutes un document que tout l’espace de travail peut exploiter et tu apprends où vit le travail partagé — les trois gestes qui couvrent la plupart des journées. Il te faut un compte connecté sur un espace de travail où le chat répond déjà — c’est le [démarrage rapide](/fr/get-started/quickstart). Discuter et parcourir fonctionnent avec le rôle **Membre** ; les deux gestes d’écriture ci-dessous (téléverser un document, déplacer une tâche) demandent **Éditeur** ou plus — si un bouton te manque, c’est la frontière de rôle, pas un espace de travail cassé. <Steps> <Step title="Discute avec un agent"> Tu as déjà envoyé un premier message dans le démarrage rapide — cette fois, regarde ce que l’agent en fait. Clique sur **Nouveau chat**, pose une question tirée de ton vrai travail et déplie les blocs repliables d’appels d’outils au-dessus de la réponse : ils montrent ce que l’agent a lu ou exécuté avant de répondre. Pour joindre un fichier à une seule conversation, colle-le, glisse-le dans le composeur ou passe par le contrôle de pièce jointe — l’agent le lit pour ce chat uniquement. [Pièces jointes](/fr/platform/chat/attachments) détaille ce qui est accepté. </Step> <Step title="Donne un document à l’espace de travail"> Les pièces jointes du chat disparaissent avec la conversation ; les connaissances restent. Pour rendre un document disponible à chaque agent et à chaque collègue, ouvre **Connaissances > Documents** et clique sur **Téléverser des documents**, puis **Depuis ton appareil**, choisis le fichier et clique sur **Téléverser**. Le document apparaît dans le tableau et s’indexe en arrière-plan — une fois indexé, les agents le citent dans leurs réponses. Le menu de téléversement apparaît pour les Éditeurs et au-dessus ; avec le rôle Membre, tu lis et cherches dans la bibliothèque, et tu confies le fichier à un Éditeur pour l’ajouter. <Frame caption="Le tableau Documents après quelques téléversements."> ![Le tableau des documents de la section Connaissances listant trois fichiers texte téléversés avec leur statut d’indexation.](/images/get-started/documents-list.webp) </Frame> <Check> Pose dans un nouveau chat une question à laquelle seul ton document peut répondre. Une réponse qui cite le document prouve que l’index fonctionne de bout en bout. </Check> </Step> <Step title="Retrouve le travail de l’équipe dans les projets"> Ouvre **Projets** dans la barre latérale. Un projet regroupe tout ce qui touche à un même effort — des tâches sur un tableau, des fichiers partagés, des chats de projet et ses propres agents. Ouvre un projet et bascule entre **Tableau** et **Liste** dans l’onglet Tâches ; avec l’accès en édition (Éditeur et au-dessus), glisse une tâche d’une colonne à l’autre pour mettre à jour son statut, et la carte qui reste dans sa nouvelle colonne après un rechargement signifie que le changement a persisté pour tout le monde. <Frame caption="Le tableau des tâches d’un projet — glisse les cartes entre les colonnes."> ![Un tableau de tâches de projet intitulé « Website relaunch » avec sept cartes réparties à une ou deux par colonne sur Backlog, À faire, En cours, En revue, Terminé et Annulé.](/images/platform/projects-task-board.webp) </Frame> </Step> <Step title="Retrouve ton chemin"> Les chats ne disparaissent jamais en silence. Clique sur **Afficher l'historique** au-dessus du composeur pour ouvrir la barre latérale d’historique — chaque chat que tu peux reprendre dans cet espace de travail, du plus récent au plus ancien. Renommer un chat lui donne un titre qui reste ; en supprimer un l’envoie dans la corbeille de l’espace de travail au lieu de le détruire. </Step> </Steps> ## Où tu en es Tu sais discuter, nourrir l’espace de travail en connaissances et naviguer dans le travail partagé — la boucle quotidienne du membre. Les lectures suivantes naturelles sont [Bases du chat](/fr/platform/chat/basics) pour le modèle mental derrière le composeur, et [Utiliser les projets](/fr/tutorials/member/use-projects) pour un parcours projet plus profond. Quand tu veux construire ton propre agent, passe au [parcours éditeur](/fr/get-started/editors). # Ton premier jour d’intégration avec Tale Source: https://tale.dev/docs/fr/get-started/developers Ce parcours s’adresse à la personne qui câble Tale dans d’autres systèmes. En dix minutes, tu crées une clé API, tu envoies ta première requête authentifiée et tu sais à quelle porte frapper pour le chat, les workflows et les documents. Il te faut le rôle **Développeur** ou plus (les paramètres d’API sont masqués en dessous) sur une instance qui tourne — [démarrage rapide](/fr/get-started/quickstart) si tu n’en as pas. Remplace `your-host.example.com` ci-dessous par l’hôte de ton instance. <Steps> <Step title="Crée une clé API"> Pour obtenir un identifiant que tes scripts peuvent porter, ouvre **Paramètres > API > REST** et clique sur **Créer une clé API**. Nomme-la d’après le système qui l’utilisera — les clés sont listées par nom, et dans un an « zapier-bridge » bat « test ». La valeur de la clé ne s’affiche qu’une fois, à la création ; range-la dans ton gestionnaire de secrets, pas dans le code. <Frame caption="Les paramètres de l’API REST — les clés se créent et se révoquent ici."> ![La page des paramètres des clés API REST listant deux clés — Production ingest et CI pipeline — dont chacune n’affiche que son préfixe, sa date d’ajout et la mention Jamais utilisée, à côté d’un bouton Créer une clé API.](/images/get-started/settings-api-keys.webp) </Frame> </Step> <Step title="Envoie la première requête"> L’appel utile le plus court liste les agents que ta clé peut voir. La clé voyage comme un token bearer ; le contexte de l’espace de travail se déduit de la clé elle-même : ```bash curl -sS https://your-host.example.com/api/v1/agents \ -H "Authorization: Bearer $TALE_API_KEY" ``` <Check> Un tableau JSON d’agents — dont l’Assistant intégré — prouve la clé, l’en-tête et la route. Un `401` signifie que l’en-tête du token est malformé ou que la clé a été révoquée. </Check> </Step> </Steps> ## Le reste de la surface Tout le reste est une variation de cette requête. Les endpoints compatibles OpenAI (`/api/v1/chat/completions`, `/api/v1/models`) signifient que les SDK existants fonctionnent en changeant l’URL de base ; les workflows se lancent par slug via `/api/v1/workflows/<slug>/run` avec la même clé Bearer, ou se déclenchent depuis l’extérieur via des URL de webhook de la forme `/api/workflows/wh/<token>` — le jeton dans l’URL est l’identifiant ; les documents se téléversent via `/api/v1/documents`. La [référence API](/fr/develop/api-reference) est l’inventaire complet avec l’authentification, les formes et les limites. ## Où tu en es Tu tiens un identifiant qui fonctionne et tu as vu la forme de requête que chaque endpoint partage. À partir d’ici, [appeler Tale depuis un script](/fr/tutorials/developer/call-tale-from-a-script) transforme le curl en vraie intégration, [déclencher un workflow par webhook](/fr/tutorials/developer/trigger-automation-via-webhook) couvre le sens entrant — tes systèmes qui déclenchent Tale — et [webhooks](/fr/develop/webhooks) documente les payloads que Tale t’envoie. # Tutoriels Source: https://tale.dev/docs/fr/tutorials/overview Les tutoriels sont des parcours de bout en bout : chacun amène une instance neuve de « je veux faire X » à un résultat qui fonctionne et se vérifie. Ils supposent que tu as le bon rôle et un espace de travail qui tourne ; les pages de concept sous [Plateforme](/fr/platform) expliquent le modèle mental, les tutoriels montrent le mécanisme du début à la fin. Si tu n’as pas encore suivi un [parcours de démarrage](/fr/get-started/quickstart), commence là — les tutoriels s’appuient sur les gestes du premier jour que ces pages couvrent. ## Choisis par rôle <CardGroup cols="2"> <Card title="Tutoriels membre" icon="message-circle" href="/fr/tutorials/member/chat-effectively"> Chatter efficacement, travailler dans les projets, mener des conversations vocales. </Card> <Card title="Tutoriels éditeur" icon="bot" href="/fr/tutorials/editor/first-agent-end-to-end"> Construire un premier agent de bout en bout, lier des connaissances, déléguer entre agents, livrer des workflows avec approbations. </Card> <Card title="Tutoriels développeur" icon="terminal" href="/fr/tutorials/developer/call-tale-from-a-script"> Appeler Tale depuis un script, déclencher des workflows par webhook, construire des outils sur mesure, monter un serveur MCP. </Card> <Card title="Tutoriels admin" icon="shield" href="/fr/tutorials/admin/office-add-in"> Installer l’add-in Office, câbler la transcription de réunion, connecter un fournisseur local. </Card> </CardGroup> ## Où cela s’inscrit Les tutoriels citent les références de fonctionnalités sous [Plateforme](/fr/platform) pour l’échafaudage conceptuel ; une fois un tutoriel parcouru, la page qui mérite une relecture est la page de concept sous-jacente. Si tu ne sais pas lequel choisir, [Construire ton premier agent](/fr/tutorials/editor/first-agent-end-to-end) est ce qui se rapproche le plus d’un « hello world » pour le produit — la plupart des capacités que tu finiras par toucher y apparaissent. # Utiliser les projets pour grouper fichiers et chats Source: https://tale.dev/docs/fr/tutorials/member/use-projects Un projet est ce vers quoi tu te tournes la deuxième fois que tu te surprends à coller le même contexte dans un chat. Il regroupe fichiers, instructions et chats autour d'une seule chose à faire — un client, un lancement, une longue enquête — pour que chaque nouvelle conversation démarre avec le contexte déjà chargé. Ce parcours mène un projet neuf de « je recharge sans cesse le même brief » à « chaque chat dans ce projet connaît déjà le brief » sur une seule instance. Il te faut un rôle Membre (le plancher pour créer un projet) et trois ou quatre fichiers que tu référence régulièrement. Le côté conceptuel vit dans [Concepts de projet](/fr/platform/projects/concepts) ; ce parcours est le mécanisme de bout en bout. ## Avant de commencer Confirme deux choses. Ton rôle est au moins Membre — la création de projet est verrouillée à Membre et au-dessus. Tu as trois à quatre fichiers qui reviennent dans les chats que tu as eus — un brief, une transcription, une liste de prix, une politique. Ils deviennent l'ensemble de travail du projet. ## Étape 1 — Créer le projet Le projet est le conteneur dans lequel vivent les autres pièces. Ouvre **Projets > Nouveau projet** et règle : - **Nom** — `Compte Acme` (ou ce qui nomme la chose à faire) - **Description** — une phrase sur l'objet du projet - **Membres** — laisse en privé pour l'instant ; tu pourras ajouter des coéquipiers après que le premier chat marche Enregistre. Le projet apparaît dans la sidebar ; un clic ouvre une vue de projet vide avec des onglets pour Connaissances, Threads, Agents et Instructions. ## Étape 2 — Charger les fichiers une seule fois Les fichiers du projet sont visibles pour chaque chat dans le projet, donc ce chargement se fait une fois et se rembourse à chaque chat ultérieur. Ouvre l'onglet **Connaissances** et glisse les trois ou quatre fichiers confirmés dans les prérequis. Chaque fichier atterrit dans le stockage du projet et s'indexe comme un document de base de connaissances. Une fois le statut **Prêt**, n'importe quel chat démarré dans le projet peut atteindre les fichiers. ## Étape 3 — Ajouter les instructions du projet Les instructions du projet encadrent chaque chat dans le projet. Elles composent avec les propres instructions de l'agent : le projet cadre le travail, l'agent cadre la réponse. Ouvre l'onglet **Instructions** et règle : `You are working on the Acme account. The contract and the call notes in the Knowledge tab are the source of truth; cite them when you make a claim. The customer's voice is conservative — drafts should not promise dates we have not confirmed.` Enregistre. Chaque nouveau chat du projet tournera désormais avec ce préambule en plus des propres instructions de l'agent. ## Étape 4 — Démarrer un chat et vérifier que le contexte suit Ouvre l'onglet **Threads** et clique **Nouveau chat**. Choisis un agent — l'Assistant par défaut suffit pour le premier run — et pose une question à laquelle un des fichiers du projet répond (`What does the contract say about the renewal clause?`). La réponse doit citer le contrat ; la citation ouvre le fichier depuis l'onglet Connaissances du projet, pas depuis la bibliothèque de l'organisation. Si l'agent répond sans citer, les fichiers du projet n'ont pas été récupérés — généralement parce que l'agent choisi n'a pas de tool de retrieval activé. Passe à un agent avec RAG actif, ou active-le sur l'Assistant pour l'usage projet. ## Où ça s'utilise Un projet avec fichiers, instructions et threads est la plus petite unité utile de contexte partagé dans Tale. La même forme passe à l'échelle — ajoute des membres pour qu'une équipe travaille le projet ensemble, ajoute un agent à périmètre projet pour verrouiller la voix, archive le projet quand le travail est livré. Pour le modèle plus profond de ce qu'est un projet et de quand on s'en sert, voir [Concepts de projet](/fr/platform/projects/concepts). Pour les agents à périmètre projet, voir [Agents de projet](/fr/platform/projects/project-agents). # Chatter efficacement Source: https://tale.dev/docs/fr/tutorials/member/chat-effectively Chatter efficacement dans Tale ne tient pas à des prompts astucieux ; il s'agit de donner au chat assez de contexte pour que le modèle saisisse ton intention dès la première lecture. Cinq petites habitudes — choisir le bon agent, choisir le bon modèle, n'attacher que ce qui compte, demander dans le périmètre, lire les citations — font passer la réponse moyenne de « merci pour le pavé » à « exactement ce qu'il me fallait ». Cette page déroule les habitudes dans l'ordre sur un chat neuf. Il te faut un rôle Membre (le plancher pour le chat) et un agent publié dans l'organisation que tu peux adresser. Le côté conceptuel vit dans [Bases du chat](/fr/platform/chat/basics) ; ce parcours est le mécanisme quotidien. ## Habitude 1 — Choisir l'agent avant le premier message L'agent est le levier au plus fort rendement par clic. L'Assistant par défaut est une toile blanche ; un agent avec du savoir lié, des tools actifs et une voix réglée le battra sur toute question non générique. Ouvre le sélecteur d'agent dans le composeur et choisis l'agent dont le périmètre correspond à ta question — Support, Sales, Research — avant de taper. Si aucun agent ne convient, laisse l'Assistant ; ne va pas vers un agent mal ajusté pour « ça ira ». Un agent mal ajusté refuse souvent ou s'écarte du savoir lié. ## Habitude 2 — Choisir le modèle adapté au message Le sélecteur de modèle à côté du sélecteur d'agent liste les modèles autorisés pour l'agent. **Auto** suffit la plupart du temps ; change quand le message change de forme. Une longue question de raisonnement veut un modèle plus grand ; une recherche rapide veut un modèle plus petit et plus rapide. Un message avec une image a besoin d'un modèle capable de vision — sans cela, l'image est silencieusement abandonnée. Le sélecteur de modèle affiche le tag (`Chat`, `Vision`, `Image`, `Embedding`) à côté de chaque nom ; fais correspondre le tag au message. ## Habitude 3 — N'attacher que ce dont l'agent a besoin Les pièces jointes invitent à l'excès. Un PDF de 200 pages en pièce jointe unique remplit le budget de contexte et dilue la réponse ; les pages pertinentes extraites dans le prompt battent le fichier entier. Si tu attaches un document long, pose-lui une question précise (« que dit la page 12 sur les remboursements ? ») plutôt qu'une question ouverte (« raconte-moi tout »). Pour les fichiers que tu référenceras souvent — une liste de prix, un document de politique — charge-les dans la section [Savoir](/fr/platform/knowledge/documents) et lie-les à un agent. Une fois liés, chaque chat avec cet agent les a sous la main sans nouveau chargement. ## Habitude 4 — Demander dans le périmètre de l'agent Chaque agent a un périmètre implicite issu de ses instructions et de son savoir lié. Demander à un agent billing une stratégie marketing donne au mieux un refus poli, au pire une hallucination. Le correctif bon marché : lis la bio de l'agent en haut du sélecteur avant de demander — elle nomme le périmètre. Si ta question est hors périmètre, change d'agent. ## Habitude 5 — Lire les citations et les suivre Quand la réponse contient des citations (les petits liens en ligne), ouvres-en une. La citation pointe sur le chunk de la source que l'agent a cité ; la lire confirme que l'agent n'a pas paraphrasé au-delà de ce que la source dit vraiment. La petite habitude de deux minutes d'ouvrir une citation par réponse attrape la petite portion de réponses où l'agent a dépassé. ## Où ça s'utilise Cinq habitudes, un chat, la même boucle à chaque ouverture de l'onglet Chat. Les habitudes se renforcent — le bon agent rend le bon modèle évident ; le bon modèle rend les citations fiables ; les citations bouclent la boucle. Pour la surface sur laquelle ces habitudes vivent, voir [Bases du chat](/fr/platform/chat/basics). Pour le côté fichiers — ce qui est collé tel quel, ce qui est indexé — voir [Pièces jointes](/fr/platform/chat/attachments). # Construire un outil personnalisé Source: https://tale.dev/docs/fr/tutorials/developer/build-a-custom-tool Un outil personnalisé est une fonction que tu écris et que le modèle d'un agent peut appeler par son nom. Tu déclares le schéma d'entrée et la forme de retour ; Tale s'occupe de la sérialisation, de la carte d'appel d'outil dans le chat et du renvoi du résultat au modèle. Ce parcours mène un outil personnalisé neuf de « j'ai une fonction en tête » à « l'agent l'appelle depuis un chat » sur une seule instance. Il te faut le rôle Developer dans l'organisation et l'accès au panneau **Paramètres > Outils personnalisés** ; tout le reste se passe dans l'UI. Le concept sous-jacent vit dans [Outils d'agent](/fr/platform/agents/tools) ; la surface côté développeur — schémas, transport, erreurs — est l'objet ici. ## Avant de commencer Confirme deux choses. Premièrement, ton rôle est au moins Developer — le panneau est caché en-dessous. Deuxièmement, tu as un agent éditable ; sinon, crée-en un via [Créer un agent](/fr/platform/agents/create) avant de continuer. Le parcours utilise un outil à une entrée et une sortie nommé `lookup_order` qui prend un ID de commande et renvoie une chaîne de statut — la plus petite forme qui exerce le schéma, l'appel et le rendu du résultat. ## Étape 1 — Définir l'outil dans Outils personnalisés Le premier geste est d'enregistrer le nom de l'outil et son JSON Schema. Le schéma est ce que voit le modèle ; sans schéma, le modèle n'a aucune idée des arguments à émettre, et l'appel ne se produit jamais. Ouvre **Paramètres > Outils personnalisés** et clique **Nouvel outil**. Donne-lui un nom (`lookup_order`), une description d'une phrase (`Look up the status of an order by ID`) et un JSON Schema pour l'entrée : ```json { "type": "object", "properties": { "orderId": { "type": "string", "description": "The order ID, e.g. ORD-12345" } }, "required": ["orderId"] } ``` Enregistre. L'outil est désormais enregistré dans le registre des outils personnalisés de l'organisation ; aucun agent ne l'utilise encore. ## Étape 2 — Câbler l'implémentation Un outil enregistré sans implémentation renvoie une erreur au modèle. Tale expose deux modes d'implémentation : un script sandbox inline (Python ou JavaScript, exécuté dans la sandbox de Tale) et un appel HTTPS sortant (Tale POST les arguments à ton endpoint, tu renvoies du JSON). Choisis le mode HTTPS pour ce parcours — c'est la forme vers laquelle tu te tournes en production. Dans le panneau de détail de l'outil, règle : - **URL de l'endpoint** — `https://your-api.example.com/lookup-order` - **Méthode** — `POST` - **En-tête d'auth** — un bearer token issu de ton gestionnaire de secrets Tale POST `{ "orderId": "..." }` à ton endpoint ; ton endpoint renvoie `{ "status": "shipped", "carrier": "DHL", "eta": "2026-06-01" }`. Enregistre. L'outil personnalisé est câblé. ## Étape 3 — Attacher l'outil à un agent Un outil câblé reste invisible aux agents jusqu'à ce qu'on en autorise un à l'appeler. Ouvre l'agent à étendre, clique **Outils**, descends jusqu'à **Outils personnalisés** et active `lookup_order`. Enregistre l'agent. Ouvre un chat avec l'agent et demande « what is the status of order ORD-12345 ». Le chat affiche une carte d'appel d'outil `lookup_order` repliée entre ton message et la réponse ; la déplier montre les arguments émis par le modèle (`{ "orderId": "ORD-12345" }`) et le JSON renvoyé par ton endpoint. Le modèle écrit ensuite la réponse avec le résultat de l'outil. ## Où ça s'utilise Un outil personnalisé est la couture entre un agent et ton domaine — recherche de commande, recherche interne, calculatrice, tout ce qu'une intégration prête à l'emploi ne couvre pas. Le schéma est ce que le modèle utilise pour décider d'appeler, alors prends le temps d'écrire une description serrée et de ne garder que les champs nécessaires. Pour des outils à partager entre organisations, voir [Serveur MCP depuis zéro](/fr/tutorials/developer/mcp-server-from-scratch) — MCP est le protocole pour « un outil, plusieurs instances Tale ». Pour le côté conceptuel de ce que font les outils dans un agent, voir [Outils d'agent](/fr/platform/agents/tools). # Appeler Tale depuis un script Source: https://tale.dev/docs/fr/tutorials/developer/call-tale-from-a-script Appeler Tale depuis un script est le chemin que tu prends quand tu veux récupérer une valeur d'un agent ou d'un workflow sans ouvrir l'UI. L'API Tale parle JSON sur HTTPS et accepte un bearer token dans l'en-tête `Authorization` ; à partir de là, chaque groupe d'endpoints est un appel REST classique. Ce parcours te mène de « je veux scripter Tale » à une réponse streamée dans ton terminal en une seule séance. Il te faut le rôle Developer (pour créer des clés API), l'URL de ton instance Tale et un shell avec `curl`, Python ou Node. La surface complète de l'API vit dans la [référence de l'API](/fr/develop/api-reference) ; cette page est le parcours de bout en bout le plus court qui la traverse. ## Avant de commencer Confirme trois choses. Ton instance est joignable en HTTPS — ouvre `https://your-host.example.com` et vérifie que le dashboard charge. Ton rôle est au moins Developer — l'entrée **Paramètres > Clés API** est cachée pour Member et Editor. Tu as au moins un agent publié — lister les agents renvoie un tableau vide sur une instance toute neuve, ce qui rend le test de fumée ambigu. ## Étape 1 — Créer une clé API Le premier geste est de créer une clé API portant sur ton utilisateur. La clé est ce que chaque appel de script transporte ; sans elle, l'API renvoie 401, et tu ne peux pas relire la clé après la création. Ouvre **Paramètres > Clés API** et clique **Nouvelle clé**. Donne-lui un nom (`local-script-test`), choisis une expiration et clique **Créer**. Copie la clé que le panneau affiche — Tale la montre une seule fois et plus jamais. Range-la en variable d'environnement pour le reste du parcours : ```bash export TALE_API_KEY="tk_..." export TALE_BASE_URL="https://your-host.example.com" ``` La clé hérite de ton rôle ; traite-la comme un mot de passe. ## Étape 2 — Test de fumée avec curl Le plus petit check de bout en bout est de lister les agents que ta clé peut voir. Si ça marche, l'auth, le réseau et l'API sont bons ; si ça échoue, le mode d'échec te dit lequel est cassé. ```bash curl -sS "$TALE_BASE_URL/api/v1/agents" \ -H "Authorization: Bearer $TALE_API_KEY" \ -H "Accept: application/json" | jq ``` Un 200 avec un corps JSON comme `{ "agents": [ ... ] }` confirme l'aller-retour. Un 401 veut dire que la clé est fausse ; un 403 veut dire que la clé est valide mais le rôle trop bas ; toute autre réponse veut dire que l'instance est injoignable ou le chemin faux. Prends un ID d'agent dans la réponse — tu en as besoin à l'étape 3. ## Étape 3 — Appeler un agent depuis Python ou Node Lister les agents est en lecture seule ; le travail utile arrive quand tu demandes une réponse à un agent. L'endpoint compatible OpenAI est l'entrée la plus simple, parce que les SDK existants tournent sans modification : ```python from openai import OpenAI import os client = OpenAI( base_url=f"{os.environ['TALE_BASE_URL']}/api/v1", api_key=os.environ["TALE_API_KEY"], ) reply = client.chat.completions.create( model="agt_your_agent_id_here", messages=[{"role": "user", "content": "Summarise the last quarter's revenue."}], ) print(reply.choices[0].message.content) ``` Le champ `model` est l'ID de l'agent ; les instructions, connaissances et outils de l'agent tournent comme configuré. La même forme en Node utilise `openai` depuis npm avec les mêmes `baseURL` et `apiKey`. Le streaming passe par `stream=True` et Server-Sent Events. ## Où ça s'utilise Un script est le chemin que tu prends quand le plan de données est JSON, pas un écran — tâches cron, checks CI, portails internes. La clé API porte ton rôle, l'endpoint compatible OpenAI est la forme la moins frictionnelle, et chaque endpoint de listing renvoie la même enveloppe `{ resource: [...] }`. Pour les déclencheurs entrants — ton système POSTe dans un workflow Tale — voir [Déclencher un workflow par webhook](/fr/tutorials/developer/trigger-automation-via-webhook). Pour la liste complète des endpoints et le modèle d'erreur, la [référence de l'API](/fr/develop/api-reference) est la seule source de vérité. # Monter un serveur MCP depuis zéro Source: https://tale.dev/docs/fr/tutorials/developer/mcp-server-from-scratch Un serveur Model Context Protocol (MCP) est un processus qui expose une liste d'outils via un petit protocole JSON-RPC. Tale enregistre un serveur MCP une fois au niveau de l'organisation ; à partir de là, chaque agent dont l'onglet Outils inclut ce serveur peut appeler ses outils. Ce parcours mène un serveur MCP tout neuf de « repo vide » à « appelé par un agent dans un chat » sur une instance Tale. Il te faut le rôle Developer, un hôte qui peut exécuter le serveur MCP (ton portable suffit pour le parcours ; un service managé ou un conteneur pour la production) et une URL HTTPS que Tale peut joindre. Les organisations Cloud joignent les URLs publiques par défaut ; les instances auto-hébergées ont besoin d'un accès réseau vers l'endroit où tourne le serveur MCP. ## Avant de commencer Confirme deux choses. Tu as Node 20 ou Python 3.11 installé — les SDK MCP officiels visent ces runtimes. L'instance Tale peut joindre l'URL de ton serveur MCP — pour le développement local, un tunnel `ngrok` ou équivalent fait l'affaire ; pour la production, héberge le serveur quelque part avec un endpoint HTTPS stable. Le côté conceptuel de MCP dans Tale vit dans [Outils d'agent](/fr/platform/agents/tools) ; ce parcours est le câblage. ## Étape 1 — Échafauder le serveur Le premier geste est de générer le serveur MCP minimal — un outil, un handler. Le SDK officiel s'occupe de la plomberie du protocole pour que tu n'écrives que l'outil. ```bash npm create mcp-server@latest hello-tale cd hello-tale ``` Ouvre `src/index.ts` et remplace l'outil d'exemple par un qui renvoie l'heure courante dans un fuseau horaire donné : ```ts server.tool( 'current_time', 'Return the current time in a given timezone', { timezone: z.string() }, async ({ timezone }) => { const now = new Date().toLocaleString('en-US', { timeZone: timezone }); return { content: [{ type: 'text', text: now }] }; }, ); ``` Lance le serveur localement : ```bash npm run start ``` Le serveur écoute sur `http://localhost:3000/mcp` par défaut. L'échafaudage est en place ; rien dans Tale ne le connaît encore. ## Étape 2 — L'exposer en HTTPS Les serveurs MCP que Tale peut appeler ont besoin d'une URL HTTPS avec un certificat valide. Pour le développement local, pointe un tunnel `ngrok` sur le port 3000 et copie l'URL publique qu'il affiche. Pour la production, héberge le serveur derrière ton ingress habituel — Caddy, Nginx, une fonction managée, tout ce qui termine le TLS. Vérifie que l'URL publique répond à un health-check : ```bash curl -sS "https://abcd.ngrok.app/mcp/health" ``` Un 200 confirme la joignabilité. Un 502 ou un timeout veut dire que le tunnel ne route pas ; relance-le ou vérifie le pare-feu. ## Étape 3 — Enregistrer le serveur dans Tale Un serveur MCP joignable reste invisible pour Tale tant que tu ne l'as pas enregistré. Ouvre **Paramètres > Intégrations > Serveurs MCP** et clique **Nouveau serveur**. Remplis : - **Nom** — `Hello Tale time` - **URL** — l'URL HTTPS publique de l'étape 2 (par ex. `https://abcd.ngrok.app/mcp`) - **Auth** — bearer token si ton serveur en exige un, aucun pour le parcours Clique **Enregistrer**. Tale appelle la méthode `list_tools` du serveur pour découvrir l'inventaire d'outils ; le panneau affiche `current_time` avec sa description. Le serveur est désormais enregistré pour toute l'organisation. ## Étape 4 — Attacher le serveur à un agent et appeler l'outil Un serveur enregistré n'est joignable que par les agents qui s'y abonnent. Ouvre n'importe quel agent, clique **Outils > MCP**, active **Hello Tale time** et enregistre. Ouvre un chat avec l'agent et demande « what time is it in Tokyo right now ». Le chat rend une carte d'appel d'outil `current_time` ; la déplier montre `{ "timezone": "Asia/Tokyo" }` et l'horodatage que ton serveur a renvoyé, et la réponse de l'agent utilise l'horodatage. ## Où ça s'utilise Un serveur MCP est la bonne forme quand un outil doit vivre hors de Tale — du code possédé par ton équipe, un service dans un autre réseau, une API tierce que tu enveloppes. Les outils personnalisés de [Construire un outil personnalisé](/fr/tutorials/developer/build-a-custom-tool) sont la bonne forme quand l'outil est ponctuel et vit dans les paramètres d'une seule organisation. Pour la grande image de comment les outils élargissent ce qu'un agent peut faire, voir [Outils d'agent](/fr/platform/agents/tools). Pour câbler une intégration qui enveloppe une API tierce plutôt que ton propre code, [Aperçu des intégrations](/fr/platform/integrations/overview) est la lecture suivante. # Déclencher un workflow par webhook Source: https://tale.dev/docs/fr/tutorials/developer/trigger-automation-via-webhook Un déclencheur webhook transforme un workflow Tale en quelque chose qu'un système externe peut allumer en POSTant du JSON. Tale reconnaît le jeton de l'URL, stocke la clé d'idempotence et lance une exécution — la même forme que tout webhook entrant doit prendre pour être sûr à rejouer. Ce parcours mène un workflow neuf de « je veux le déclencher depuis l'extérieur » à « un événement de commande POSTe et le workflow tourne » sur une seule instance. Il te faut le rôle Developer dans l'organisation, un workflow existant (ou le démarrage vide) et un shell avec `curl`. Le contrat webhook complet — signature, idempotence, retries — vit dans [Webhooks](/fr/develop/webhooks) ; ce parcours est la plus petite utilisation de bout en bout du côté entrant. ## Avant de commencer Confirme deux choses. Le workflow que tu vas déclencher existe et est publié — les brouillons ne se déclenchent pas. Ton rôle est au moins Developer — créer des clés de déclencheur est restreint à Developer et au-dessus. Si tu n'as pas encore de workflow, le petit canonique est « logue la charge utile dans l'enregistrement d'exécution » ; crée-le via [Workflow avec approbations](/fr/tutorials/editor/workflow-with-approvals) et retire l'étape d'approbation pour ce parcours. ## Étape 1 — Ajouter un déclencheur webhook au workflow Le premier geste est de lier un déclencheur webhook au workflow. Sans déclencheur, le workflow n'est appelable que depuis l'UI ; avec un, il obtient une URL sur laquelle n'importe quel système peut POSTer. Ouvre l'onglet **Déclencheurs** du workflow et clique sur **Ajouter un webhook**. Tale émet une **URL de webhook** unique, avec le justificatif embarqué comme jeton dans le chemin — il n'y a ni nom de déclencheur ni clé séparée. Enregistre l'URL quand elle s'affiche : quiconque la détient peut tirer le workflow, traite-la donc entièrement comme un secret. Supprimer le webhook la révoque. ```bash export TALE_TRIGGER_URL="https://your-host.example.com/api/workflows/wh/<token>" ``` ## Étape 2 — POSTer une charge utile depuis curl L'URL de webhook est un endpoint POST classique. Le corps devient l'entrée de la première étape du workflow ; un en-tête `Idempotency-Key` rend les rejeux sûrs — un rejeu renvoie l'exécution d'origine au lieu d'en lancer une nouvelle. ```bash curl -sS "$TALE_TRIGGER_URL" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: order-12345" \ -d '{ "orderId": "12345", "amount": 199.0 }' ``` Un 200 renvoie `{ "status": "accepted", "workflowSlug": "..." }`. Le workflow tourne maintenant en asynchrone ; ouvre l'onglet **Exécutions** du workflow et tu devrais voir une exécution en cours avec ta charge utile comme entrée du déclencheur. Un 404 veut dire que le jeton de l'URL ne correspond à aucun webhook ; un 403 que le webhook est désactivé ou que le workflow n'est plus installé ; un 429 que l'IP appelante a atteint la limite de débit. ## Étape 3 — Sécuriser les retries avec l'idempotence Les systèmes externes rejouent sur timeouts et erreurs 5xx ; sans idempotence, un rejeu déclenche le workflow deux fois. L'en-tête `Idempotency-Key` de l'étape 2 est la solution : Tale mémorise la clé par organisation et répond au rejeu par `{ "status": "duplicate", "executionId": "..." }` — l'exécution d'origine — au lieu de déclencher à nouveau. Teste-le en rejouant exactement la même requête curl ci-dessus. La réponse porte l'`executionId` du premier appel, et l'onglet **Exécutions** du workflow montre toujours une seule exécution. Change la clé en `order-12346` et curl à nouveau — celui-là déclenche une seconde exécution. Le système source doit utiliser une clé stable et déterministe par événement logique. Un schéma courant est `<event-type>-<event-id>` ; n'utilise jamais un UUID aléatoire généré au moment du rejeu, sinon chaque rejeu crée une nouvelle exécution. ## Où ça s'utilise Les déclencheurs webhook sont la moitié entrante de l'API de workflows de Tale — la couture où ton CRM, ton système de commandes ou ton outil de monitoring POSTe. Sers-t'en pour « ceci s'est passé dans notre monde, lance un workflow Tale dessus » ; tourne-toi vers la [référence de l'API](/fr/develop/api-reference) quand tu veux une réponse synchrone à la place. Pour la moitié sortante — Tale POSTant à ton URL quand un événement Tale arrive — et pour le contrat complet de signature et de retries, voir [Webhooks](/fr/develop/webhooks). La configuration côté workflow du déclencheur vit sur la page [Déclencheurs de workflow](/fr/platform/automations/triggers). # Brancher un fournisseur LLM local Source: https://tale.dev/docs/fr/tutorials/admin/connect-local-provider Un fournisseur local est le chemin vers des modèles qui tournent dans ton propre périmètre — pas d'appels d'API sortants, pas de facture au token, pas de transcription chez un tiers. Ce parcours emmène une instance Tale auto-hébergée de « J'ai un endpoint Ollama, LM Studio ou vLLM » à « Un agent dans l'organisation appelle un modèle local et la réponse streame en retour. » Le parcours s'adresse à un Admin sur un install auto-hébergé ; les organisations Cloud ne tendent pas la main vers ton réseau et sautent cette page. Il te faut le rôle Admin dans Tale, un serveur d'inférence local joignable depuis le conteneur `tale-platform`, et un modèle déjà téléchargé ou chargé sur ce serveur. La mécanique sous-jacente du fournisseur est documentée dans [Fournisseurs](/fr/self-hosted/configuration/providers) ; cette page parcourt le chemin UI et vérifie le résultat de bout en bout. ## Avant de commencer Confirme quatre choses. Ton rôle est Admin ou Propriétaire — le panneau **Fournisseurs** est caché en dessous. Ton serveur d'inférence local tourne et répond à `GET /v1/models` (ou l'équivalent Ollama `GET /api/tags`) depuis l'intérieur du réseau Docker Tale. Au moins un modèle est chargé — les utilisateurs d'Ollama ont lancé `ollama pull llama3.1:8b` ou similaire, les utilisateurs de LM Studio ont un modèle chargé dans l'onglet serveur, les utilisateurs de vLLM ont démarré le serveur avec `--model` pointant sur un checkpoint. Et le chemin réseau de `tale-platform` vers l'hôte d'inférence est ouvert sur le port d'inférence (typiquement `11434` pour Ollama, `1234` pour LM Studio, `8000` pour vLLM). ## Étape 1 — Rendre le serveur d'inférence joignable depuis Tale Le premier geste est de confirmer que `tale-platform` atteint le serveur d'inférence par son nom d'hôte. Sans ça, chaque appel de modèle fait remonter une erreur de connexion et le picker affiche le fournisseur en **error**. Quand le serveur d'inférence tourne sur le même hôte Docker, le nom d'hôte joignable dépend d'où le serveur lui-même tourne. Un conteneur Ollama dans le même réseau compose est `http://ollama:11434`. Un serveur LM Studio ou vLLM qui tourne sur l'hôte (hors compose) est `http://host.docker.internal:1234` sur macOS et Windows, ou l'IP de bridge de l'hôte sous Linux. Lance un curl ponctuel depuis le conteneur `tale-platform` pour vérifier avant d'ouvrir l'UI : ```bash docker compose exec platform curl -sf http://ollama:11434/api/tags ``` Une liste JSON des modèles téléchargés est le signal de succès. Une erreur connection-refused signifie que le nom d'hôte est faux ou que le serveur d'inférence n'écoute pas sur l'interface que le conteneur peut atteindre. ## Étape 2 — Enregistrer le fournisseur dans Tale Un serveur joignable ne fait rien tant que Tale ne connaît pas l'URL et la forme de protocole qu'il parle. L'entrée du fournisseur dit à Tale où envoyer les requêtes et quel dialecte compatible OpenAI utiliser. Ouvre **Paramètres > Fournisseurs** et clique **Ajouter un fournisseur**. Choisis le type de fournisseur qui correspond à ton serveur : **Ollama** pour un serveur Ollama, ou **Compatible OpenAI** pour LM Studio et vLLM (les deux exposent la forme `/v1` d'OpenAI). Remplis l'**URL de base** avec la valeur que tu as vérifiée à l'étape 1 ; laisse le champ clé d'API vide pour Ollama, mets-le à n'importe quelle chaîne pour LM Studio (le serveur l'ignore), mets-le à ton token configuré pour vLLM si tu as démarré le serveur avec `--api-key`. Clique **Enregistrer**. Tale appelle immédiatement l'endpoint de liste de modèles du fournisseur ; la ligne passe au vert et le picker de modèles se remplit de ce que le serveur a rapporté. ## Étape 3 — Allowlister les modèles que tu veux appelables Un fournisseur enregistré sans modèle allowlisté est invisible à chaque agent. L'allowlist est le contrat entre l'organisation et le fournisseur — choisir le modèle est la porte. Dans la ligne du fournisseur, déplie le picker de modèles. Chaque modèle de la liste upstream affiche une case à cocher plus le tag que Tale a inféré (`chat`, `embedding`, `vision`). Coche les modèles que tu veux que les agents appellent ; un modèle tagué chat est ce à quoi un agent se lie par défaut. Clique **Enregistrer l'allowlist**. Si tu veux que le modèle local soit le défaut à l'échelle de l'organisation pour les nouveaux chats, fais défiler en haut de la liste des fournisseurs et choisis-le sous **Modèle par défaut**. Les agents existants gardent leur liaison précédente ; les nouveaux atterrissent sur le modèle local à la requête suivante. ## Étape 4 — Vérifier avec un chat d'agent La preuve que le câblage marche est une réponse de chat qui streame depuis le serveur local. Sans cette étape tu ne sais pas si le picker de modèles _a l'air_ juste seulement. Ouvre ou crée un agent, règle son modèle sur un des modèles locaux que tu as allowlisté et démarre un chat avec un prompt court (`Réponds avec le seul mot "prêt"`). La réponse streame en tokens en quelques secondes ; la tool-call card du chat affiche le nom du modèle et le fournisseur que tu as enregistré. Suis le log du serveur d'inférence sur l'hôte pendant que tu envoies le prompt — Ollama logge la ligne de requête, LM Studio imprime un résumé de requête, vLLM imprime la latence de génération. Voir la requête frapper le serveur local est la vérification que le trafic reste dans ton réseau et ne rebondit pas via une API externe. ## Dépannage - **Symptôme :** la ligne du fournisseur affiche **error** avec `connection refused`. **Cause :** l'URL de base n'est pas joignable depuis le conteneur `tale-platform`. **Correction :** répète le `docker compose exec platform curl` de l'étape 1 ; ajuste le nom d'hôte (souvent `host.docker.internal` sur macOS/Windows, l'IP de bridge sous Linux). - **Symptôme :** le picker de modèles est vide après **Enregistrer**. **Cause :** le serveur d'inférence est joignable mais aucun modèle n'est chargé. **Correction :** lance `ollama pull <model>` ou charge un modèle dans LM Studio / vLLM, puis clique **Rafraîchir les modèles** sur la ligne du fournisseur. - **Symptôme :** la réponse du chat est un toast d'erreur (`model not found`). **Cause :** le nom du modèle auquel l'agent est lié ne correspond pas à l'identifiant upstream. **Correction :** ouvre le dropdown de modèle de l'agent et re-choisis depuis la liste vivante — les tags Ollama comme `:latest` comptent en upstream et doivent correspondre exactement. - **Symptôme :** l'enregistrement du fournisseur est refusé parce que l'URL de base pointe vers `localhost`, `127.0.0.1` ou une IP privée. **Cause :** Tale bloque par défaut les hôtes de fournisseur privés et loopback, par sécurité contre le SSRF. **Correction :** utilise plutôt le nom d'hôte interne au réseau (`http://ollama:11434`, `http://host.docker.internal:1234`) ; si tu dois pointer vers une adresse privée ou loopback, définis `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS=1` sur le service platform. ## Où cela s'inscrit Un fournisseur local est la couture entre Tale et tes propres GPU — la même mécanique d'allowlist qu'un fournisseur cloud, mais aucun trafic ne quitte l'hôte. Les prochaines lectures naturelles sont [Fournisseurs](/fr/self-hosted/configuration/providers) pour l'équivalent en forme de fichier de ce que tu viens de faire dans l'UI, et [Durcissement](/fr/self-hosted/operate/security/hardening) pour les garanties d'allowlist egress qui empêchent un agent de retomber par accident sur un modèle cloud quand le local n'est pas joignable. # Installer le complément Outlook Source: https://tale.dev/docs/fr/tutorials/admin/office-add-in Le complément Outlook fait apparaître une sidebar Tale dans Outlook sur le web, sur poste de travail et sur mobile. Depuis la sidebar, un membre choisit un agent, glisse le fil de courriel ouvert comme contexte et récupère un brouillon de réponse sans changer d'application. Ce parcours s'adresse à un Admin qui déploie le complément à l'échelle de l'organisation ; il couvre le déploiement du manifeste, la connexion et la vérification. Il te faut le rôle Admin dans Tale, un tenant Microsoft 365 où tu peux gérer les Integrated Apps et une instance Tale joignable depuis le cloud Microsoft 365. Les organisations Cloud sont joignables par défaut ; les instances auto-hébergées ont besoin d'une URL HTTPS publique. ## Avant de commencer Confirme trois choses côté Microsoft : tu es Global Administrator (ou disposes du rôle Exchange Admin avec Integrated Apps), le déploiement centralisé est activé pour ton tenant, et la boîte aux lettres de test n'a pas bloqué les compléments via une mailbox policy. Côté Tale, ouvre **Paramètres > Intégrations** et vérifie que **Microsoft 365** est listé — c'est là que le complément publie l'URL du manifeste. ## Étape 1 — Récupérer l'URL du manifeste depuis Tale Le complément parle à Tale via un manifeste XML hébergé par le centre d'administration Microsoft 365. Tale génère le manifeste par instance pour que la sidebar pointe sur ton URL et non sur un endpoint multi-tenant partagé. Ouvre **Paramètres > Intégrations > Microsoft 365** et copie l'**URL du manifeste du complément** que le panneau affiche. Tu devrais voir une URL se terminant par `/integrations/office/manifest.xml`. Ouvre-la dans un nouvel onglet pour confirmer qu'elle renvoie du XML et pas une page d'erreur HTML — si elle échoue, ton instance n'est pas joignable depuis l'extérieur ou l'intégration est désactivée. ## Étape 2 — Déployer via le centre d'administration Microsoft 365 Le manifeste dit à Microsoft 365 quelles boîtes aux lettres voient la sidebar et depuis quelle URL la charger. Le déploiement centralisé est le chemin pris en charge ; le side-loading utilisateur par utilisateur fonctionne mais ne survit pas à une migration de boîte. Ouvre le centre d'administration Microsoft 365, navigue vers **Paramètres > Applications intégrées > Charger des applications personnalisées**, choisis **Complément Office** et **Fournir le lien vers le fichier manifeste**, et colle l'URL de l'étape 1. Choisis l'audience du déploiement — tout le tenant, un groupe de sécurité ou une liste précise d'utilisateurs. Soumets. Microsoft confirme le déploiement par une bannière verte ; le déploiement atteint typiquement les boîtes en une heure, parfois quelques heures sur un grand tenant. ## Étape 3 — Se connecter depuis la sidebar Ouvre Outlook avec un utilisateur de l'audience, clique sur un message quelconque et cherche l'icône Tale dans le ruban du message. Un clic ouvre la sidebar ; à la première ouverture elle demande à l'utilisateur de se connecter avec son compte Tale. La connexion passe par OAuth via l'instance Tale — même fournisseur d'identité que l'application web. Une fois connecté, la sidebar liste les agents disponibles pour cet utilisateur. En choisir un et cliquer **Rédiger une réponse** intègre le fil de courriel ouvert comme contexte et streame une réponse dans la sidebar. L'utilisateur révise, modifie et clique **Insérer** pour la déposer dans la fenêtre de rédaction Outlook. ## Où ça s'utilise Le complément est le chemin le plus léger vers « Tale là où tes membres travaillent déjà » — pas de changement de portail, pas de copier-coller. La sidebar est une fine enveloppe autour des mêmes agents que tu publies dans [Créer un agent](/fr/platform/agents/create) ; les changements d'instructions, de connaissances ou d'outils d'un agent atterrissent dans la sidebar à la requête suivante. Pour la grande histoire d'intégration — Slack, Gmail, serveurs MCP personnalisés — voir [Aperçu des intégrations](/fr/platform/integrations/overview). Si tu exploites une instance auto-hébergée et que l'URL du manifeste n'est pas joignable depuis Microsoft 365, la page [Linux serveur](/fr/self-hosted/install/linux-server) couvre le prérequis HTTPS public. # Piper les transcriptions de réunions dans la Base de connaissances Source: https://tale.dev/docs/fr/tutorials/admin/meeting-transcription Une transcription de réunion est l'un des documents les plus précieux qu'un projet puisse garder — noms, décisions, suivis, le tout dans un endroit cherchable. Ce parcours intègre Meetily, un outil local de transcription de réunions, avec un projet Tale pour que chaque transcription que produit Meetily atterrisse dans la Base de connaissances du projet comme document à part entière. Le parcours s'adresse à un Admin sur une instance Tale auto-hébergée qui l'associe à un install Meetily sur le même réseau. Il te faut un rôle Admin dans Tale, un install Meetily joignable depuis le conteneur `tale-platform` et un projet dans Tale avec une Base de connaissances vers laquelle router les transcriptions. Le concept de Base de connaissances vit dans [Base de connaissances](/fr/platform/knowledge/overview) ; cette page est le parcours d'intégration, pas la page de concept. ## Avant de commencer Confirme quatre choses. Ton rôle est Admin ou Propriétaire dans Tale — le panneau **Intégrations** est caché en dessous. Meetily tourne et produit des transcriptions dans un format que Tale accepte (Markdown, texte brut ou VTT). L'hôte Meetily est joignable depuis `tale-platform` par son chemin webhook ou son dossier partagé. Et le projet cible existe déjà dans Tale avec une Base de connaissances attachée — l'intégration écrit _dans_ une Base de connaissances, elle n'en crée pas. ## Étape 1 — Choisir un chemin de livraison Meetily peut remettre des transcriptions à Tale sous deux formes, et elles ont des propriétés opérationnelles différentes. Le choix verrouille la suite du parcours. Le chemin **webhook** fait que Meetily POSTe chaque transcription terminée à un endpoint d'ingestion Tale dès que la réunion finit ; la transcription est dans la Base de connaissances en quelques secondes après la fin de la réunion. Le chemin **dossier partagé** fait que Meetily écrit les transcriptions comme fichiers dans un répertoire que la plateforme Tale poll chaque minute ; la latence va jusqu'à une minute mais le chemin n'a besoin d'aucune URL publique et survit aux redémarrages de Meetily sans logique de retry. Choisis le webhook quand les deux services tournent dans le même réseau et que tu veux une indexation rapide ; choisis le dossier partagé quand Meetily tourne sur un poste qui s'éveille de manière irrégulière ou quand l'équipe d'exploitation préfère une trace d'audit basée fichier. ## Étape 2 — Créer l'endpoint d'ingestion ou le dossier dans Tale Tale doit savoir où les transcriptions atterriront et à quel projet elles appartiennent. Sans cette liaison, les transcriptions arrivent mais aucune Base de connaissances ne les réclame. Ouvre **Paramètres > Intégrations**, clique **Ajouter une intégration** et choisis **Transcriptions de réunions**. Choisis le projet dans la liste déroulante — la Base de connaissances que le projet utilise est la destination. Choisis le chemin de livraison que tu as choisi à l'étape 1. Si tu as choisi le webhook, Tale génère une URL de la forme `https://<ton-hôte>/integrations/transcripts/<token>` et la montre une fois. Copie l'URL ; elle sert aussi de credential bearer, donc traite-la comme un secret. Si tu as choisi le dossier partagé, Tale demande le chemin sur disque que `tale-platform` doit surveiller (typiquement `/data/transcripts/<project-slug>`). Crée le répertoire sur l'hôte, donne-lui une appartenance de groupe qui correspond à l'utilisateur du conteneur `tale-platform`, et confirme. ## Étape 3 — Pointer Meetily vers Tale Meetily doit maintenant savoir où livrer chaque transcription. Les réglages vivent dans la config propre à Meetily. Pour le chemin webhook, ouvre les paramètres de Meetily et ajoute une destination webhook avec l'URL de l'étape 2. Choisis le format de transcription — le Markdown est ce qui se lit le mieux dans un aperçu de document Tale, mais le VTT et le texte brut s'indexent correctement tous les deux. Pour le chemin dossier partagé, règle le répertoire de sortie de transcriptions de Meetily sur le chemin que tu as créé à l'étape 2. Assure-toi que Meetily écrit un fichier par réunion, nommé avec le titre de la réunion et l'horodatage. Termine une courte réunion de test dans Meetily et observe le panneau Intégrations de Tale. La ligne d'intégration affiche un horodatage **Dernière livraison** qui se met à jour dans la minute (mode dossier) ou en quelques secondes (mode webhook). ## Étape 4 — Vérifier que le document atterrit et s'indexe La preuve que le câblage marche est une transcription visible dans la Base de connaissances comme document cherchable. Sans cette étape tu ne sais pas si Tale a reçu le fichier _et_ l'a indexé. Ouvre le projet cible, navigue vers sa Base de connaissances et cherche la nouvelle transcription en haut de la liste des documents. Clique dans l'aperçu — la transcription se rend comme document avec le titre de la réunion en nom de document et la date de la réunion en created-at. Attends que le badge d'indexation se libère (quelques secondes pour une courte transcription, jusqu'à une minute pour une longue), puis lance une recherche sur un nom ou une phrase dont tu te souviens de la réunion de test. La transcription devrait être le premier résultat avec la phrase surlignée. Si le document est là mais que le badge d'indexation reste orange, l'indexation est en retard — la page [Dépannage](/fr/self-hosted/operate/observability/troubleshooting) nomme les symptômes. ## Notes de confidentialité L'intégration traverse un réseau dans chaque direction et la forme des données compte. - **Meetily → Tale.** Le corps de la transcription traverse, plus le titre de la réunion, l'horodatage et les étiquettes de locuteur que Meetily a attachées. L'audio ne traverse pas — Meetily transcrit localement et seul le texte est livré. Le chemin webhook utilise HTTPS avec le token bearer dans l'URL ; le chemin dossier utilise un chemin de système de fichiers sans réseau du tout. - **Tale → Meetily.** Rien. L'intégration est à sens unique ; Tale ne rappelle jamais Meetily. - **Tale → services externes.** Le texte de la transcription traverse vers le fournisseur d'embedding qui est lié à la Base de connaissances. Si le fournisseur d'embedding est local (Ollama, LM Studio, vLLM via [Brancher un fournisseur LLM local](/fr/tutorials/admin/connect-local-provider)), aucun texte de transcription ne quitte l'hôte. Si le fournisseur d'embedding est OpenAI, Anthropic ou un autre endpoint hébergé, le texte de la transcription est envoyé à cet endpoint pour vectorisation selon la politique de traitement des données de ce fournisseur. Quand les transcriptions contiennent du contenu que l'organisation ne peut pas envoyer à un fournisseur cloud, le pattern pris en charge est de lier la Base de connaissances du projet à un modèle d'embedding local. La liaison du fournisseur se passe dans les paramètres de la Base de connaissances, pas dans cette intégration. ## Où cela s'inscrit L'intégration de transcription de réunions est l'exemple le plus net de « Tale indexe ce que tes autres outils produisent déjà » — pas de copier-coller, pas d'upload manuel, pas d'étape supplémentaire dans le flux de réunion. Les prochaines lectures naturelles sont [Base de connaissances](/fr/platform/knowledge/overview) pour à quoi la transcription indexée peut alors servir à l'intérieur d'un agent, et [Brancher un fournisseur LLM local](/fr/tutorials/admin/connect-local-provider) quand la section ci-dessus te pousse à garder l'étape d'embedding sur l'hôte. # Construire un agent avec du savoir Source: https://tale.dev/docs/fr/tutorials/editor/agent-with-knowledge Un agent avec du savoir est la forme vers laquelle tu te tournes quand le modèle doit répondre à partir de documents spécifiques — ton manuel produit, tes politiques, les notes d'appel du trimestre dernier — et non depuis ce qu'il a appris durant l'entraînement. L'agent récupère des chunks dans les sources liées au moment de la réponse et les cite. Ce parcours mène un agent neuf de « je veux qu'il connaisse mes docs » à « la réponse cite le bon document » sur une seule instance. Il te faut un rôle Éditeur, la capacité de charger des documents dans la base de connaissances, et environ trois documents à lier. Le côté conceptuel vit dans [Savoir de l'agent](/fr/platform/agents/knowledge) ; ce parcours est le mécanisme de bout en bout. ## Avant de commencer Confirme trois choses. Ton rôle est au moins Éditeur — l'édition d'agent est verrouillée à Éditeur et au-dessus. Tu as au moins trois documents prêts à charger (PDF, DOCX, Markdown — tout ce que la base de connaissances accepte). Tu as un fournisseur configuré pour que l'agent puisse tourner — sans cela, la réponse de test à la fin échoue sur l'appel au modèle. ## Étape 1 — Charger les documents dans la base de connaissances Le premier geste est de mettre les documents dans la base de connaissances de Tale. Des documents hors de la base ne se lient pas ; l'agent ne voit que des sources qu'il peut nommer. Ouvre **Savoir > Documents** et clique **Charger**. Glisse les trois documents, donne-leur des titres parlants, et attends que la colonne de statut affiche **Prêt** pour chacun. Le statut parcourt `chargé → en traitement → prêt` ; le traitement découpe le document en chunks et calcule les embeddings. Un PDF typique atteint **Prêt** en une ou deux minutes. Si un document reste sur `en traitement` plus de cinq minutes, ouvre sa ligne pour voir l'erreur — la cause la plus fréquente est un format non supporté (PDF en images, fichiers protégés par mot de passe) ou un fichier plus gros que la limite d'upload de l'organisation. ## Étape 2 — Créer l'agent Un document lié s'accroche à un agent, donc l'agent doit exister d'abord. Ouvre **Agents > Nouvel agent** et remplis les quatre boutons comme base : - **Nom** — `Docs Q&A` - **Instructions** — `You answer questions strictly from the bound documents. If you cannot find the answer in the documents, say so explicitly. Cite the document title for every claim.` - **Tools** — active **RAG** ; tout le reste désactivé - **Modèle** — celui que l'organisation utilise par défaut Enregistre et publie. L'agent existe désormais mais n'a aucun savoir — il refusera toute question, faute de source à trouver. ## Étape 3 — Lier les documents La liaison est la couture qui donne à l'agent un accès retrieval à un sous-ensemble de la base de connaissances. Ouvre l'onglet **Savoir** de l'agent et clique **Savoir de l'agent**. Choisis les trois documents de l'Étape 1 et enregistre. L'onglet Savoir liste maintenant trois sources liées. Le tool RAG de l'agent ne récupère que parmi ces trois ; rien d'autre dans la base de connaissances n'est atteignable depuis cet agent, pas même les autres documents de la même bibliothèque. ## Étape 4 — Poser une question et vérifier la citation Ouvre un chat avec `Docs Q&A` et pose une question à laquelle un des documents répond. La réponse arrive en streaming avec des citations en ligne — survoler montre le titre du document, cliquer ouvre le document au chunk cité. Pose une question qu'aucun des documents ne couvre ; l'agent doit refuser explicitement selon l'instruction, et non inventer une réponse. Si l'agent invente quand même une réponse, les instructions ne sont pas assez strictes — ajoute un cas de refus explicite (« If you cannot find the answer in the bound documents, respond with exactly: 'I could not find this in the bound documents.' ») et republie. ## Où ça s'utilise Les quatre gestes ci-dessus sont le build canonique de « l'agent qui répond depuis tes docs » : charger, créer l'agent avec RAG actif, lier, vérifier avec une citation. La même forme passe à l'échelle — lie dix documents au lieu de trois, ajoute un site web ou un dossier client, change de modèle. Ce sont les liaisons, pas le modèle, qui font que l'agent est le tien. Pour le côté conceptuel — comment le retrieval se compose avec les autres boutons de l'agent — voir [Concepts des agents](/fr/platform/agents/concepts). Pour l'histoire plus large de la base de connaissances — Clients, Produits, Fournisseurs, Sites web — voir [Aperçu du savoir](/fr/platform/knowledge/overview). # Construire un workflow avec approbation Source: https://tale.dev/docs/fr/tutorials/editor/workflow-with-approvals Un workflow avec une décision humaine au milieu est la forme vers laquelle tu te tournes quand le travail comporte un brouillon, une relecture et une action — et que tu veux une personne entre le brouillon et l'action. Le run se met en pause comme **En attente de saisie** jusqu'à ce que quelqu'un réponde ; l'étape suivante ne se déclenche qu'avec le feu vert. Ce parcours construit un workflow de résumé quotidien de cette façon, et tu croises en chemin les deux portes humaines : approuver la proposition de l'Éditeur IA, puis répondre au run en pause. Il te faut un rôle Éditeur et un agent qui produit un brouillon (le premier agent utile de [Construire ton premier agent](/fr/tutorials/editor/first-agent-end-to-end) suffit). Le côté conceptuel vit dans [Concepts d’automatisation](/fr/platform/automations/concepts) et [Concepts d'approbation](/fr/platform/approvals/concepts) ; ce parcours est le mécanisme de bout en bout. ## Avant de commencer Confirme trois choses. Ton rôle est au moins Éditeur — l'édition de workflow est verrouillée à Éditeur et au-dessus. Tu as un agent rédacteur de brouillon prêt ; sans lui, l'étape de brouillon n'a rien à invoquer. Et tu peux répondre à la relecture toi-même — le run en pause attend un humain, et dans ce parcours, cet humain, c'est toi. ## Étape 1 — Ouvrir un workflow dans l'éditeur Les workflows vivent dans l'automatisation qu'ils animent : ouvre l'automatisation et son onglet **Éditeur** est le workflow, avec le graphe d'étapes sur le canevas. Pour ce parcours, ouvre un workflow à toi ou un workflow du pack task-ops provisionné dans ton organisation — tout ce que tu as le droit de modifier convient, puisque c'est de toute façon l'Éditeur IA qui construit la nouvelle définition pour toi. ## Étape 2 — Décrire le workflow à l'Éditeur IA Active l'**Éditeur IA** dans la barre d'outils du canevas et décris toute la forme en un seul message : > Chaque jour ouvré à 8 h, fais résumer par l'agent <ton agent> les messages clients non lus d'hier en un paragraphe, puis fais relire le brouillon par un humain, et n'envoie au canal d'équipe que le texte approuvé. L'Éditeur IA répond par une carte de proposition — **Créer le workflow** avec le nombre d'étapes, ou **Mettre à jour le workflow** s'il retravaille celui que tu as ouvert. Tant que la carte est en attente, rien ne touche la définition : déplie-la, vérifie les étapes listées — une étape **LLM** pour le brouillon, la pause de relecture, l'envoi — et approuve-la. Le changement s'applique et se versionne comme n'importe quelle sauvegarde manuelle. ## Étape 3 — Attacher la planification Passe à l'onglet **Déclencheurs** et clique **Ajouter une planification**. Prends le préréglage **Tous les jours** et ajuste le cron aux jours ouvrés (`0 8 * * 1-5`) — ou décris l'horaire en langage courant et clique **Générer** pour laisser l'IA écrire le cron. **Variables du workflow** se préremplit depuis le schéma d'entrée du workflow ; laisse la proposition telle quelle. La ligne apparaît avec l'interrupteur **Actif** déjà activé. ## Étape 4 — Lancer et répondre à la relecture De retour dans l'éditeur, ouvre **Tester le workflow**, colle le JSON d'entrée proposé et clique **Exécuter**. Le panneau reflète le run étape par étape : l'étape de brouillon se déclenche, puis le run se met en pause — **En attente de saisie** — et la relecture arrive comme une carte-formulaire qui porte le brouillon. Remplis-la et clique **Soumettre la réponse** pour approuver, ou **Répondre différemment** pour renvoyer du texte libre ; le run reprend avec ta réponse et l'étape d'envoi se déclenche. Ouvre l'onglet **Exécutions** et déplie le run : le journal montre une entrée par étape — le brouillon produit par l'agent, qui a répondu à la relecture et quoi, et l'envoi avec sa sortie. Ce journal est la piste d'audit ; le même enregistrement naît à chaque futur run planifié. ## Où ça mène Rédiger, décider, agir — avec la décision entre les mains d'un humain — est le plus petit workflow-avec-approbation utile, et tu l'as construit sans poser une seule étape à la main : l'Éditeur IA a proposé, tu as approuvé, le run a demandé, tu as répondu. La même forme passe à l'échelle — ajoute une seconde relecture avant une étape destructrice, ou laisse [Approbations dans les workflows](/fr/platform/automations/approvals-in-workflows) te montrer les autres portes autour d'un workflow. Pour le vocabulaire derrière définition, déclencheur et exécution, [Concepts d’automatisation](/fr/platform/automations/concepts) est la page que ce parcours a supposée connue. # Confier du travail à un worker Source: https://tale.dev/docs/fr/tutorials/editor/delegate-between-agents Quand une demande mérite son propre contexte ciblé — recherche citée, extraction en masse, longue rédaction — l'assistant lance un **worker** : un agent éphémère composé pour exactement cette tâche, avec exactement les capacités que l'assistant lui accorde depuis son propre ensemble. Il n'y a rien à configurer ; ce parcours fait tourner un job de recherche de bout en bout et te montre comment lire la carte de job. Le versant conceptuel (sous-ensembles de capacités, budgets, méthodologies) vit dans [Workers d'agent](/fr/platform/agents/delegation). ## Avant de commencer Il te faut un agent de chat (l'Assistant intégré fonctionne tel quel) sur un modèle avec tool-calling. Pour des sources web en direct, connecte une intégration de recherche comme Tavily sous **Paramètres > Intégrations** — sans elle, le worker retombe sur la simple récupération web et le dit dans son résultat. ## Étape 1 — Demande quelque chose qui mérite un worker Ouvre un chat avec `Assistant` et demande un travail ouvert et citable, par exemple : `Fais une recherche sur l'état des batteries à électrolyte solide — marché, acteurs clés, sources citées.` Une question factuelle rapide ne lance pas de worker (et ne le devrait pas) ; les workers sont pour les tâches qui profitent de l'isolation. ## Étape 2 — Observe la carte de job L'assistant appelle `spawn_agent` et une **carte de job** apparaît sous son tour : le nom du worker, un statut en direct et la checklist de progression du worker qui se remplit pendant qu'il planifie et traite les sous-questions. La carte ne bloque jamais le champ de saisie — tu peux continuer à écrire pendant que le worker tourne. Si la carte affiche une note « ignoré », l'assistant a demandé quelque chose hors de ses propres accès (par exemple une intégration non connectée) ; l'exécution continue avec le reste, et la note te dit quoi connecter pour la prochaine fois. ## Étape 3 — Lis le résultat et la transcription Quand le job se termine, l'assistant replie le livrable du worker dans sa réponse — pour une recherche : une conclusion, des points clés avec citations en ligne et les sources. Sur la carte, déplie **l'activité du worker** pour voir la transcription complète : chaque recherche, chaque appel d'outil et le raisonnement du worker. Cette transcription est la piste d'audit à montrer quand on te demande ce que l'agent a réellement fait. ## Étape 4 — Quand quelque chose tourne mal Un worker à court de temps ou frappé par une erreur se termine avec un statut visible sur la carte — `temps écoulé` ou `échoué` — avec sa progression partielle intacte. L'assistant rapporte ce qu'il a obtenu et continue lui-même là où il peut. Rien n'échoue en silence : si le worker avait besoin d'une information que toi seul peux donner, l'assistant te la demande directement. ## Où cela s'inscrit Une demande, un worker, une carte : c'est la plus petite forme utile. La même mécanique passe à l'échelle avec plusieurs workers dans un tour — chacun a sa carte, sa progression et sa transcription. Pour des étapes fixes avec validations ou planification entre elles, prends plutôt une [automatisation](/fr/platform/automations/concepts). # Construire ton premier agent Source: https://tale.dev/docs/fr/tutorials/editor/first-agent-end-to-end Un premier agent est la plus petite chose utile dans Tale : des instructions plus un modèle, parfois avec un tool ou un document lié. Ce parcours tourne les quatre boutons dans l'ordre — instructions, savoir, tools, modèle — et te laisse avec un agent publié qui répond à une vraie question dans un chat. La forme se généralise : chaque agent que tu construis plus tard est les mêmes quatre gestes avec d'autres choix. Il te faut un rôle Éditeur et un modèle marqué Chat configuré chez le fournisseur de l'organisation. Le côté conceptuel vit dans [Concepts des agents](/fr/platform/agents/concepts) ; ce parcours est le mécanisme de bout en bout. ## Avant de commencer Confirme trois choses. Ton rôle est au moins Éditeur — l'édition d'agent est verrouillée à Éditeur et au-dessus. L'organisation a un fournisseur configuré et au moins un modèle marqué Chat dessus ; sans cela, la réponse de test à la fin échoue sur l'appel au modèle. Tu as une question en tête à laquelle l'agent doit répondre — choisis quelque chose d'assez étroit pour qu'un paragraphe d'instructions puisse l'encadrer, comme « résume un message client entrant en une phrase plus une action suivante recommandée ». ## Étape 1 — Écrire les instructions Les instructions sont le system prompt — la prose qui encadre chaque réponse. Le premier bouton est celui que la plupart des gens forcent trop. Ouvre **Agents > Nouvel agent** et règle : - **Nom** — `Triage assistant` - **Instructions** — `You read a customer message and produce two lines. Line one: a one-sentence summary in plain English. Line two: a recommended next action — reply, escalate, or close. If the message is blank or off-topic, refuse and say so.` Enregistre comme brouillon pour l'instant ; la publication vient après les autres boutons. Des instructions courtes, tranchées et concrètes battent les longues — garde les règles sous un paragraphe. ## Étape 2 — Décider du savoir Le savoir est ce que l'agent peut référencer au moment de la réponse. Pour ce premier agent, laisse Savoir vide : le travail est de lire le message, pas de récupérer quoi que ce soit. L'onglet Savoir reste intact. Si tu voulais ajouter du savoir plus tard — disons une matrice d'escalade que l'agent doit consulter — tu chargerais le document, ouvrirais l'onglet **Savoir** de l'agent et le lierais. Le mécanisme complet vit dans [Agent avec savoir](/fr/tutorials/editor/agent-with-knowledge). ## Étape 3 — Choisir les tools Les tools sont ce que l'agent peut faire au-delà de répondre en texte. Pour le triage, aucun tool n'est nécessaire : l'agent lit l'entrée et écrit la sortie. Ouvre l'onglet **Tools** et laisse chaque interrupteur désactivé. Chaque tool que tu accordes élargit la frontière de confiance ; garde la liste courte. Si l'agent doit écrire l'action recommandée dans un CRM, tu activerais plus tard le tool d'intégration correspondant — mais pas avant que la version texte seul fonctionne. ## Étape 4 — Choisir le modèle et publier Ouvre l'onglet **Modèle** et choisis le défaut de l'organisation comme primaire ; règle un modèle plus petit en fallback pour que l'agent tourne encore quand le primaire est rate-limited. Enregistre, puis clique **Publier**. L'agent est désormais visible dans le chat pour toute personne avec le bon rôle. Ouvre un chat avec `Triage assistant` et colle un vrai message client. La réponse doit atterrir en deux lignes selon les instructions — un résumé en une phrase et une action recommandée. Si le format dérive, resserre les instructions et republie ; c'est la boucle dans laquelle tu passes le plus de temps. ## Où ça s'utilise Quatre boutons, un agent publié, une réponse vérifiée : la même forme que suit chaque agent que tu construiras plus tard. Les parcours suivants se spécialisent sur un bouton chacun — [Agent avec savoir](/fr/tutorials/editor/agent-with-knowledge) sur le deuxième, [Confier du travail à un worker](/fr/tutorials/editor/delegate-between-agents) sur le troisième. Pour la page de concept qui nomme les quatre boutons et les arbitrages entre eux, voir [Concepts des agents](/fr/platform/agents/concepts). Pour la version et le rollback une fois que l'agent mûrit, voir [Versions d'agent](/fr/platform/agents/versions). # Trust et conformité Source: https://tale.dev/docs/fr/cloud/trust-and-compliance Trust et conformité sur Cloud est la page qu'un auditeur veut. Elle nomme les cadres contre lesquels la plateforme est certifiée, sépare proprement les responsabilités entre Tale et ton organisation, liste les contrôles de protection des données à ta disposition, et te dit qui appeler quand quelque chose tourne mal. Le contenu ici est descriptif — ce qui est livré aujourd'hui, quelles preuves Tale peut fournir sur demande. Les documents légaux eux-mêmes (DPA, conditions, politique de confidentialité) vivent sous [Mentions légales](/fr/legal/privacy) ; cette page est la référence rapide de l'opérateur. ## Un contrôle déroulé — journaux d'audit de bout en bout Le responsable conformité de l'organisation doit démontrer que « chaque changement de contrôle d'accès est journalisé avec l'acteur, la cible et l'horodatage ». Les [Journaux d'audit](/fr/platform/admin/governance/audit-logs) de Tale enregistrent chaque invitation de membre, changement de rôle, suppression et réinitialisation 2FA avec l'ID utilisateur de l'acteur, l'ID du membre affecté, et un horodatage ISO. Les journaux sont immuables — restaurer un instantané ne les modifie pas — et conservés selon le plancher configuré par l'organisation. Le responsable exporte une plage de dates en CSV, la remet à l'auditeur, et l'exemple déroulé valide le contrôle. ## Certifications et cadres Tale Cloud est actuellement audité ou attesté contre les cadres suivants ; les rapports de certification sont disponibles sous NDA via le support : - SOC 2 Type II (annuel) - ISO/IEC 27001 - Contrôles alignés RGPD (lignes directrices EDPB appliquées) - Contrôles alignés LPD pour la région Suisse (nLPD) En attente ou prévus : BAA HIPAA (clients entreprise US), attestations régionales supplémentaires à mesure que la liste des régions s'agrandit. ## Responsabilité partagée | Contrôle | Tale | Toi | Preuve | | --------------------------------- | -------------------- | -------------------- | ---------------------------------------------------------- | | Disponibilité d'infrastructure | ✓ | | Page de statut, rapport SLA SOC 2 | | Chiffrement des données au repos | ✓ | | Description d'architecture | | Chiffrement en transit | ✓ | | Terminaison TLS par le edge de Tale | | Identité des membres et rôles | | ✓ | [Membres et rôles](/fr/platform/admin/members-and-roles) | | Émission et rotation des clés API | | ✓ | [Clés API](/fr/platform/admin/api-keys) | | Filtrage de contenu et DLP | Fournit les crochets | Configure les règles | [Guardrails](/fr/platform/admin/governance/guardrails) | | Rétention des journaux d'audit | Fournit le stockage | Règle la rétention | [Rétention](/fr/self-hosted/configuration/retention) | | Demandes de personnes concernées | Fournit le workflow | Initie et approuve | [DSR](/fr/platform/admin/governance/data-subject-requests) | | Identifiants fournisseurs | | ✓ | [Providers](/fr/platform/admin/providers) | ## Contrôles de protection des données Dans le produit, trois surfaces de contrôle comptent pour la conformité : - **Journaux d'audit** — enregistrement immuable de qui a fait quoi ; rétention configurable. - **Conservation légale** — exempte un ensemble d'enregistrements de la rétention jusqu'à la levée ; couvert dans [Conservation légale](/fr/platform/admin/governance/legal-hold). - **Demandes de personnes concernées** — le workflow demande → prise en charge → effacement → audit ; couvert dans [DSR](/fr/platform/admin/governance/data-subject-requests). ## Signaler les incidents Le contact incident sécurité de Tale est `security@tale.dev`. La divulgation de vulnérabilités présumées suit la politique de divulgation responsable sur le même e-mail. Les bulletins de sécurité côté client sont publiés sur la page de statut et envoyés par e-mail au Owner de l'organisation. ## Où ça s'inscrit Trust et conformité est la page du moment d'audit ; [Résidence des données](/fr/cloud/data-residency) est la page du moment d'architecture ; [Sous-traitants](/fr/legal/subprocessors) est la page liste-de-vendeurs. Un auditeur veut généralement les trois en même temps — mets-les toutes en favoris. Si tu opères en auto-hébergé, les contrôles sont les mêmes ; ce qui change est qui fait tourner l'infrastructure en dessous — voir [Aperçu auto-hébergé](/fr/self-hosted/overview). # Cloud Source: https://tale.dev/docs/fr/cloud Tale Cloud est l’édition gérée. Tale exploite l’infrastructure, tes données sont ancrées en Suisse ou dans l’UE, et la seule préoccupation opérationnelle de ton équipe est d’utiliser le produit. Le code est identique à la version auto-hébergée ; la différence porte sur qui le fait tourner. Cette section couvre ce qui est spécifique à Cloud — l’onboarding, les régions et la résidence des données, la facturation, la posture de conformité que tu peux remettre à un auditeur, et comment migrer vers de l’auto-hébergé si tes besoins changent. Toute autre référence de fonctionnalité vit un onglet plus loin, sous Plateforme, identique quelle que soit l’édition. ## Pages de cette section <CardGroup cols="2"> <Card title="Onboarding" icon="rocket" href="/fr/cloud/onboarding"> Demande d’instance, création de l’organisation, configuration du premier fournisseur de modèle, publication du premier agent. Environ une heure pour un Éditeur. </Card> <Card title="Résidence des données" icon="map-pin" href="/fr/cloud/data-residency"> Où vivent tes données, quels sous-traitants les touchent et ce qui change quand tu changes de région. </Card> <Card title="Facturation" icon="credit-card" href="/fr/cloud/billing"> Plans, sièges, composants facturés, budgets, et où trouver la facture. </Card> <Card title="Confiance et conformité" icon="shield-check" href="/fr/cloud/trust-and-compliance"> Les certifications dont Tale dispose, le partage des responsabilités, et les preuves que tu peux remettre à un auditeur. </Card> <Card title="Migrer vers l’auto-hébergé" icon="server" href="/fr/cloud/migrate-to-self-hosted"> Exporter depuis Cloud, monter une instance auto-hébergée, importer. </Card> </CardGroup> ## Où cela s’inscrit Cloud est la porte d’entrée pratique ; Plateforme est l’endroit où le vrai travail se passe. Une fois ton organisation connectée et le premier agent en route, ton équipe passe la quasi-totalité de son temps dans les pages Plateforme, pas ici. La seule page qui mérite une relecture à chaque changement de ta posture opérationnelle est [Résidence des données](/fr/cloud/data-residency) — elle expose chaque système externe que tes données traversent. # Facturation Source: https://tale.dev/docs/fr/cloud/billing La facturation sur Cloud est mesurée, pas par siège. Tu paies pour les tokens consommés par les chats et les agents, les minutes vocales, les générations d'images et le stockage ; la plateforme elle-même vient avec l'organisation. Cette page parcourt une ligne de facture, liste les composants mesurés, et pointe vers les contrôles de budget qui évitent les surprises. La facture arrive chaque mois par e-mail et est aussi visible dans le produit sous **Paramètres > Facturation**. Cloud facture dans la devise de facturation de ton organisation, qui par défaut est USD à l'inscription et peut être changée avant la première facture. ## Une ligne de facture déroulée Une ligne sur la facture lit `Models — Anthropic Claude Sonnet — 1.2M tokens — $4.32`. Tale l'a assemblée depuis le ledger d'usage par message : chaque réponse de chat enregistre le modèle utilisé, le compte de tokens, et le coût au tarif actif quand l'appel s'est terminé. Les lignes s'agrègent par fournisseur et par modèle par période de facturation. Le détail est téléchargeable en CSV depuis le même écran. ## Plans Tale propose deux plans — **Community** et **Enterprise**. Community est l'édition open source auto-hébergée ; tu la fais tourner sur ta propre infrastructure et le concept de facturation décrit sur cette page ne s'applique pas. **Enterprise** est le plan géré (Cloud ou auto-hébergé) avec un SLA de support, des contrôles de rétention des journaux d'audit, SSO, le DPA et l'accès à des régions au-delà du défaut. Le plan affecte les frais fixes mensuels et les barrières fonctionnelles, pas le coût par appel ; le tarif mesuré pour les tokens, la voix et le stockage ci-dessous s'applique à Enterprise sur Cloud. ## Composants mesurés | Composant | Unité | Compté comme | Où le voir | | ---------- | ----------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------- | | Modèles | Tokens (in + out) | Par appel fournisseur ; marge en plus du tarif fournisseur | [Analytique d'utilisation](/fr/platform/admin/governance/usage-analytics) | | Voix (TTS) | Caractères parlés | Par réponse d'agent rendue en audio | Analytique d'utilisation | | Voix (STT) | Secondes audio | Par message utilisateur enregistré | Analytique d'utilisation | | Images | Générations | Par image retournée par le modèle | Analytique d'utilisation | | Stockage | Go-mois | Usage du stockage objet moyenné sur la période | Page de facturation | ## Budgets et dépassements Règle les budgets sous [Politiques et limites](/fr/platform/admin/governance/policies-and-limits). Une **Budget rule** plafonne la dépense mensuelle par utilisateur, par équipe, par rôle ou par organisation. Atteindre un budget se lit comme un toast clair — **Limite d'utilisation atteinte** — et met en pause la portée affectée jusqu'à ce que le budget soit relevé ou que la période bascule. La précédence par défaut est `utilisateur > équipe > rôle > défaut` — la règle la plus spécifique l'emporte. Un **Warning threshold (%)** sur la même règle émet une notification quand l'usage franchit le seuil sans bloquer. Va vers l'avertissement quand tu veux savoir sans interrompre ; va vers les limites dures quand les dépassements sont une urgence. ## Où trouver l'usage La vue la plus riche est [Analytique d'utilisation](/fr/platform/admin/governance/usage-analytics) sous Gouvernance — elle décompose l'usage par **Top Assistants**, **Top Models**, **Top Voice Models** et **Per-User Usage**, tous filtrables par plage de dates. La page Facturation dans Paramètres montre la vue niveau facture ; Analytique d'utilisation montre la vue opérationnelle. ## Où ça s'inscrit La facturation est la page phare de l'opérateur ; [Analytique d'utilisation](/fr/platform/admin/governance/usage-analytics) est la page quotidienne. Si le coût de ton organisation est surtout des tokens, la page à mettre en favori est la table Top Models — elle fait remonter quels modèles l'équipe a adoptés et te dit si un basculement vers une alternative moins chère ferait la différence. Pour les utilisateurs auto-hébergés, le concept de facturation ne s'applique pas (tu paies ton fournisseur directement) ; la page de visibilité des coûts, si. # Résidence des données Source: https://tale.dev/docs/fr/cloud/data-residency La résidence des données sur Cloud répond à deux questions que chaque audit finit par poser : quelle région détient tes données au repos, et quels systèmes externes les touchent en vol. Cette page trace un seul aller-retour de chat de bout en bout, liste les classes de données, et nomme chaque sous-traitant que tes messages traversent. La région par défaut pour les nouvelles organisations Cloud est la Suisse. Changer de région après l'inscription est une migration, pas un basculement de réglage — recréer une organisation dans la région UE est plus rapide que d'en déplacer une existante. Choisis une fois ; choisis délibérément. ## Un exemple déroulé — un aller-retour de chat L'utilisateur à Zurich ouvre Chat et envoie « résume le dernier appel client ». La requête frappe le edge de Tale dans la région choisie, atterrit sur `tale-platform`, qui appelle dans `tale-convex` (le backend), lit les connaissances liées depuis la base de connaissances, et émet un appel sortant vers le fournisseur de modèles contre lequel l'agent est configuré. La récupération de connaissances tourne dans le backend Convex — elle interroge directement la base de connaissances, sans service de récupération séparé sur le chemin. Le fournisseur de modèles retourne des tokens ; Tale les streame en retour sur le même chemin. La réponse et les citations atterrissent dans la base de données opérationnelle, le corpus reste dans la base de connaissances, et les deux sont répliqués dans la région. Deux flèches franchissent la frontière régionale dans ce trajet : l'appel vers le fournisseur de modèles (toujours externe) et tout sous-traitant déclenché par les outils de l'agent (fetch web, lecture OneDrive, serveur MCP dans une autre région). Tout le reste reste dans la région. ## Régions primaires | Région | Postgres | Stockage objet | Réplica DR | | ---------------- | --------- | -------------- | ---------- | | Suisse | Zurich | Zurich | Genève | | Union européenne | Francfort | Francfort | Dublin | Le réplica DR sert au plan de reprise après sinistre, pas au trafic actif. Les données d'une région ne circulent jamais vers le primaire ou le réplica de l'autre. ## Ce qui reste dans la région, ce qui en sort | Type de données | Lié à la région | Traverse | Notes | | ---------------------------------------- | --------------- | -------- | ------------------------------------------------------------------------------ | | Chats et messages | ✓ | | | | Documents et embeddings de connaissances | ✓ | | | | Configuration d'organisation et rôles | ✓ | | | | Journaux d'audit | ✓ | | | | Requêtes vers le fournisseur de modèles | | ✓ | Va vers le fournisseur configuré ; choisis un endpoint régional si disponible. | | Synchronisation OneDrive | | ✓ | La région de stockage de Microsoft s'applique. | | Récupérations de l'outil web | | ✓ | Là où l'URL résout. | ## Sauvegardes et DR Tale prend un instantané des deux bases Postgres — la base opérationnelle et le corpus de connaissances — chaque jour, et du stockage objet chaque heure. Les instantanés sont chiffrés au repos avec des clés détenues par Tale ; le réplica DR reçoit une copie dans la région. Les restaurations à partir d'instantanés sont une opération initiée par le client routée via le support ; le SLA couvre le temps de restauration. ## Changer de région Un changement de région s'implémente comme un export depuis la région courante, un import dans la nouvelle région, et un basculement DNS. La procédure est la même que [Migrer vers auto-hébergé](/fr/cloud/migrate-to-self-hosted), sauf que les deux côtés sont des régions Cloud ; attends-toi à une indisponibilité de l'ordre de la minute et une fenêtre planifiée. Il n'y a pas de bascule de région in-place. ## Où ça s'inscrit La résidence des données est la première page que toute revue de conformité lit. Couple-la avec [Trust et conformité](/fr/cloud/trust-and-compliance) (quel cadre couvre quoi) et [Sous-traitants](/fr/legal/subprocessors) (la liste de chaque système externe nommé ci-dessus). Si ton organisation envisage l'auto-hébergement pour une exigence de résidence, [Aperçu auto-hébergé](/fr/self-hosted/overview) est la lecture suivante — faire tourner la pile sur ton propre matériel déplace chaque flèche de cette page à l'intérieur de ta propre frontière. # Migrer vers auto-hébergé Source: https://tale.dev/docs/fr/cloud/migrate-to-self-hosted La migration de Cloud vers l'auto-hébergement est une vraie procédure, pas un basculement de réglage. Les données s'exportent, la nouvelle instance importe, le DNS bascule vers le nouvel hôte, et ton équipe se connecte dans la même organisation qu'avant — mêmes agents, mêmes chats, même historique d'audit. Ce tutoriel parcourt la procédure et pointe vers les endroits où elle déraille. Va-y quand l'auto-hébergement convient vraiment mieux : la résidence des données exige du matériel sous ton contrôle, les coûts à l'échelle rendent on-premise moins cher que au-token, ou l'organisation a décidé de faire tourner la pile elle-même. Pour la plupart des équipes, Cloud reste le bon choix — relis [Onboarding Cloud](/fr/cloud/onboarding) si tu hésites encore. ## Avant de commencer Mets ces choses en place avant d'exporter quoi que ce soit : - Un hôte cible qui répond aux prérequis auto-hébergé — voir [Démarrage rapide](/fr/self-hosted/install/quickstart) pour le cahier des charges. - Le contrôle DNS sur le domaine que ton organisation utilise actuellement ; tu le balanceras lors de la bascule. - Une fenêtre de maintenance d'au moins une heure. L'import lui-même est plus rapide, mais la propagation DNS et la validation ajoutent du temps. - Une confirmation de sauvegarde récente dans le journal d'audit de ton organisation Cloud. Rien n'est supprimé dans la source pendant une migration, mais le bundle d'export est ta preuve que l'état source était cohérent. ## Ce qui est transféré et ce qui ne l'est pas Transféré : chats, threads, messages, pièces jointes, documents, embeddings de connaissances, agents, versions d'agents, workflows, exécutions, journaux d'audit, membres, rôles, équipes, branding, clés API, métadonnées d'intégrations. Pas transféré : les intégrations externes doivent être réauthentifiées contre la nouvelle instance (les identifiants vivent chez le fournisseur, pas dans le bundle d'export) ; les workflows actifs en cours se mettent en pause et reprennent sur la nouvelle instance après la bascule ; les audios vocaux conservés au-delà de la fenêtre de rétention de l'organisation restent dans le stockage objet Cloud jusqu'à leur purge. ## Étape 1 — Exporter Ouvre **Paramètres > Organisation** sur Cloud et clique **Export**. Le dialogue lance l'export en arrière-plan et envoie par e-mail un lien de téléchargement une fois terminé. L'export est un seul bundle chiffré ; l'e-mail contient la clé de déchiffrement. Télécharge le bundle et garde la clé séparément. ## Étape 2 — Mettre en place l'instance cible Sur l'hôte cible, suis [Démarrage rapide](/fr/self-hosted/install/quickstart) jusqu'à l'étape premier-admin. N'invite pas encore d'utilisateurs — l'import écrase la liste des membres. Confirme que la nouvelle instance démarre et que tu peux te connecter comme Owner. ## Étape 3 — Importer Sur l'instance cible, connecte-toi comme Owner et visite `/_internal/import` (lié depuis la page Paramètres après une installation neuve). Téléverse le bundle, colle la clé de déchiffrement, et clique **Import**. L'import est une opération longue ; la page montre la progression par classe de données. Quand la page se résout à **Import complete**, la nouvelle instance porte l'état complet de l'organisation source. ## Étape 4 — Basculer le DNS Mets à jour l'enregistrement DNS du domaine de l'organisation pour pointer vers la nouvelle instance. Une fois la propagation effectuée et le TLS de la nouvelle instance en bonne santé, les utilisateurs qui se connectent arrivent sur l'instance auto-hébergée avec leurs identifiants existants. L'organisation Cloud devient en lecture seule à ce moment — pour éviter la dérive, archive-la sous **Paramètres > Organisation** sur Cloud après quelques jours de confiance. ## Dépannage - **L'export reste bloqué à « preparing ».** Les très grosses organisations (>100 Go) prennent plus de temps que la fenêtre e-mail suppose. Ouvre un ticket support ; l'export va jusqu'au bout en arrière-plan. - **L'import échoue sur un schéma incompatible.** Ton instance cible fait tourner une version Tale plus ancienne que ce que l'export Cloud attend. Mets à jour la cible avant de retenter — le bundle est compatible vers l'avant, pas vers l'arrière. - **Les membres ne peuvent pas se connecter après la bascule.** Les cookies de session sont scopés à l'ancien hôte. Les membres se ré-authentifient une fois ; les réglages SSO et 2FA traversent. - **Les workflows affichent « en pause » après l'import.** Attendu — l'import préserve l'état mais ne reprend pas automatiquement les exécutions en cours. Ouvre chaque workflow et clique **Resume** après avoir confirmé que l'instance cible est joignable depuis les déclencheurs externes. ## Où ça s'utilise La migration est en pratique une opération à sens unique — une fois auto-hébergé, tu y restes, sauf changement structurel. La migration inverse (auto-hébergé vers Cloud) suit la même forme avec les mêmes outils et est prise en charge, mais rare. Si tu es encore sur Cloud et tu lis ça pour le contexte, la page à enchaîner est [Aperçu auto-hébergé](/fr/self-hosted/overview) ; elle nomme ce que tu prends sur les épaules. # Onboarding Cloud Source: https://tale.dev/docs/fr/cloud/onboarding <!-- Internal, for agents editing this page: Tale Cloud has no self-serve sign-up — tale.dev ships no sign-up route. A Cloud customer fills in the demo request form (https://tale.dev/request-demo — /de/ and /fr/ localized), and the Tale team sets up a dedicated demo instance for them. The journey below only starts once that instance exists; from there it deliberately mirrors normal first-run onboarding (sign-up on the customer's own instance, org wizard, providers). Keep the request-your-instance step first and do not change the entry point back to a tale.dev sign-up. --> Ce parcours va de la demande de démo à une organisation Cloud prête pour la production avec un agent qui fonctionne. Le résultat est une organisation où ton équipe peut se connecter, choisir un agent qui marche et lui demander quelque chose d’utile — rien d’extraordinaire encore, juste le socle sur lequel tout le reste se construit. Il te faut une adresse e-mail qui fonctionne et la possibilité de la vérifier. Le parcours ne suppose aucune connaissance préalable de Tale ; si quelque chose ci-dessous mentionne un concept que tu n’as pas rencontré, la page liée l’introduit. Une fois ton instance prête, la partie pratique prend moins d’une heure — environ la moitié part dans l’étape du fournisseur, le reste est surtout des clics. ## Avant de commencer Cale trois choses : - Une adresse e-mail pour le premier compte **Propriétaire** de l’organisation. Ce compte portera le rôle le plus élevé ; choisis quelqu’un qui ne quittera pas l’équipe la semaine prochaine. - Des identifiants API pour au moins un fournisseur de modèles (OpenAI, Anthropic, Azure ou un compatible local). Le portail du fournisseur montre où ils vivent. - La région où ancrer tes données. Cloud propose la Suisse et l’UE ; le choix fait partie de la mise en place de l’instance — changer plus tard est une vraie migration. ## De la demande de démo à un agent qui fonctionne <Steps> <Step title="Demande ton instance"> Tale Cloud ne s’active pas en libre-service — chaque organisation Cloud tourne sur sa propre instance, montée pour toi par l’équipe Tale. Remplis le formulaire de demande de démo sur [tale.dev/fr/request-demo](https://tale.dev/fr/request-demo) ; le nom et l’e-mail suffisent, la société et une ligne sur ce que tes agents doivent faire aident l’équipe à ajuster la mise en place. L’équipe monte ensuite ta propre instance de démo — un environnement dédié, pas un essai partagé — et revient vers toi dès qu’elle est prête. </Step> <Step title="Crée ton organisation"> Ouvre ton instance et inscris-toi. Le formulaire demande ton nom, ton e-mail et un mot de passe ; vérifie le lien reçu par e-mail. L’écran suivant demande le **Nom de l'organisation** — le nom affiché que ton équipe verra dans le coin de chaque page. Choisis-en un qui survit à un rebranding. <Frame caption="L’étape espace de travail — le nom que ton équipe voit partout."> ![L’assistant de création d’organisation à son étape espace de travail, avec Northlight Labs saisi dans le champ Nom de l’organisation et le bouton Suivant actif.](/images/get-started/org-create-wizard.webp) </Frame> Le premier utilisateur devient automatiquement **Propriétaire** de l’organisation. Tu retrouveras ton rôle plus tard dans la section **Membres** sous **Paramètres > Organisation** si tu l’oublies. </Step> <Step title="Invite le premier admin"> Ouvre **Paramètres > Organisation**, descends jusqu’à la section **Membres** et clique sur **Ajouter un membre**. Saisis l’e-mail de l’admin et assigne le rôle **Admin**. L’invité reçoit un e-mail avec un lien magique ; il s’inscrit et atterrit dans l’organisation avec le rôle que tu as assigné. La règle de sécurité « au moins 2 Admins » empêche une organisation de s’enfermer dehors en retirant son seul Admin — invite un second admin avant toute action qui l’exige. Pour la matrice des rôles (qui peut faire quoi), voir [Membres et rôles](/fr/platform/admin/members-and-roles). </Step> <Step title="Ajoute un fournisseur de modèles"> Ouvre **Paramètres > Fournisseurs IA** et clique sur **Ajouter un fournisseur**. Choisis le fournisseur pour lequel tu as des identifiants et colle la clé API. Enregistre. Tale valide la clé en arrière-plan ; une confirmation sur la ligne du fournisseur signifie que la clé fonctionne. Si la validation échoue, la ligne affiche l’erreur telle quelle — la cause la plus fréquente est un espace autour de la clé. <Frame caption="Le fournisseur connecté — à partir d’ici, chaque agent peut répondre."> ![La page des paramètres des fournisseurs d’IA listant un seul fournisseur connecté, OpenRouter, avec son URL de base et ses 52 modèles.](/images/get-started/settings-providers.webp) </Frame> <Note> C’est l’étape où la plupart des sessions d’onboarding calent — le portail du fournisseur est souvent un autre login, et l’équipe doit creuser pour retrouver la clé. Si la validation reste bloquée plus d’une minute, recharge la page ; la clé est enregistrée dès que **Enregistrer** confirme, la ligne a parfois juste besoin d’un rechargement pour se mettre à jour. </Note> </Step> <Step title="Publie ton premier agent"> Ouvre **Agents** et clique sur **Créer un agent**. Choisis le modèle que tu viens d’ajouter. Écris un bloc d’instructions d’un paragraphe — la voix dans laquelle l’agent doit répondre, le domaine qu’il connaît, les cas qu’il refuse. Enregistre. Active **Visible dans le chat**. L’agent est maintenant joignable depuis n’importe quel chat de l’organisation. Pour un parcours plus profond sur ce qui fait un bon agent, voir [Créer un agent](/fr/platform/agents/create). </Step> <Step title="Ouvre le chat"> Clique sur **Nouveau chat** dans la barre latérale. Choisis l’agent dans le sélecteur, tape une question que son domaine couvre, envoie. <Check> La réponse arrive en streaming — si elle atterrit comme tu l’as voulue dans les instructions, l’organisation a fini son onboarding. </Check> Trois suites qui valent la peine maintenant, pendant que tout est frais : - Ouvre **Paramètres > Branding** et téléverse le logo de l’organisation. - Règle la langue par défaut de l’organisation sous **Paramètres > Organisation**. - Parcours [Trust et conformité](/fr/cloud/trust-and-compliance) pour savoir quoi montrer à un auditeur avant qu’on te le demande. </Step> </Steps> ## Dépannage - **L’e-mail d’invitation n’arrive jamais.** Vérifie le dossier spam de l’invité. Tale envoie depuis `noreply@tale.dev` ; certains filtres d’entreprise le mettent en quarantaine. - **La validation du fournisseur échoue avec « invalid key ».** Recopie la clé depuis le portail du fournisseur — la copie embarque souvent un espace en tête ou en queue. - **L’agent n’apparaît pas dans le sélecteur du chat.** Confirme que **Visible dans le chat** est activé pour l’agent. ## Où ça s’utilise Tu as maintenant une organisation avec un agent qui fonctionne et un admin en plus de toi. Le parcours suivant naturel est [Construire ton premier agent de bout en bout](/fr/tutorials/editor/first-agent-end-to-end) — même forme, mais avec un agent qui fait un vrai travail de domaine grâce à des liaisons de connaissances. Si tu es venu évaluer Cloud face à l’auto-hébergé, [Migrer vers auto-hébergé](/fr/cloud/migrate-to-self-hosted) est le parcours inverse. # Auftragsverarbeiter Source: https://tale.dev/docs/de/legal/subprocessors Ein Auftragsverarbeiter ist eine Drittpartei, die Tale beauftragt, personenbezogene Kundendaten in seinem Auftrag zu verarbeiten. Die Liste unten bezieht sich auf Tale Cloud; Self-hosted-Betreiber kontrollieren ihre eigene Infrastruktur, und die Auftragsverarbeiter-Liste solcher Deployments sind die Anbieter, die du wählst. Wesentliche Ergänzungen werden 30 Tage im Voraus angekündigt, und Org-Inhaber werden per E-Mail benachrichtigt. Lies das, wenn ein Auditor fragt, wer sonst noch deine Daten berührt. Komm zurück, wenn ein Beschaffungs-Review die aktuelle Anbieterliste und den Standort jedes einzelnen braucht. Diese Seite spiegelt **Anhang A** der [Auftragsverarbeitungsvereinbarung](https://tale.dev/de/legal/data-processing-agreement) — beide werden in derselben Änderung aktualisiert. Die Endpunkte und Datenflüsse der Tale-Plattform selbst sind in der öffentlichen [API-Dokumentation](https://demo.tale.dev/docs) beschrieben. ## Keine Nutzung von Kundendaten zum Modell-Training Tale nutzt Kundendaten — Prompts, Eingaben, Ausgaben, Embeddings, Audio, Bilder oder daraus abgeleitete Artefakte — nicht zum Training, Fine-Tuning oder zur Verbesserung von KI-Modellen. Jeder unten genannte KI-Auftragsverarbeiter ist über seine Enterprise- oder API-Bedingungen mit Tale vertraglich an dasselbe gebunden. Eine Abweichung ist nur durch eine gesonderte, beidseitig unterzeichnete Opt-in-Vereinbarung möglich; die fortgesetzte Nutzung der Leistungen, Einstellungs-Schalter im Produkt oder implizite Zustimmung gelten nicht. Die bindende Klausel steht in [Auftragsverarbeitungsvereinbarung § 5](https://tale.dev/de/legal/data-processing-agreement#5-ki-verarbeitung--keine-nutzung-zum-training-oder-zur-verbesserung). ## Aktuelle Auftragsverarbeiter Jeder Name verlinkt auf die öffentlich zugängliche AVV (oder gleichwertige Bedingungen) des jeweiligen Anbieters. Zertifizierungen und Trust-Seiten stehen im nächsten Abschnitt. Das Plattform-Hosting folgt der Datenresidenz-Wahl deiner Org: die erste Tabelle gilt für Orgs in der EU/im EWR, die zweite für Schweizer Orgs. KI-Aufrufe (LLM-Inferenz, Audio- und Bild-Verarbeitung) werden für alle Orgs in der EU/im EWR verarbeitet — kein eingesetzter KI-Auftragsverarbeiter betreibt eine Schweizer Region, und keiner dieser Aufrufe wird in Drittstaaten wie den USA verarbeitet. ### Orgs in der EU/im EWR | Auftragsverarbeiter (Firma) | Ladungsfähige Adresse | Art der Leistung | Ort der Verarbeitung | | ----------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | [Akenes SA (Exoscale)](https://www.exoscale.com/dpa/) | Boulevard de Grancy 19A, 1006 Lausanne, Schweiz | Bereitstellung der Cloud-Infrastruktur (Rechenzentrum): Hosting der Tale-Cloud-Plattform — VMs, Container-Runtime, Datenbank und Storage. | Deutschland (Region Frankfurt). | | [OpenRouter, Inc.](https://openrouter.ai/privacy) | 169 Madison Avenue, New York, NY 10016, USA | Bereitstellung der LLM-Inferenz (Chat, Vision, Embeddings), der Audio-Verarbeitung (Speech-to-Text und Text-to-Speech) sowie der Bild-Verarbeitung und -Generierung. | Europäische Union (In-Region-Routing über `eu.openrouter.ai`: Prompts und Antworten werden ausschließlich innerhalb der EU verarbeitet). | ### Schweizer Orgs | Auftragsverarbeiter (Firma) | Ladungsfähige Adresse | Art der Leistung | Ort der Verarbeitung | | ----------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | [Akenes SA (Exoscale)](https://www.exoscale.com/dpa/) | Boulevard de Grancy 19A, 1006 Lausanne, Schweiz | Bereitstellung der Cloud-Infrastruktur (Rechenzentrum): Hosting der Tale-Cloud-Plattform — VMs, Container-Runtime, Datenbank und Storage. | Schweiz (Zürich; Disaster-Recovery-Replikat in Genf). | | [OpenRouter, Inc.](https://openrouter.ai/privacy) | 169 Madison Avenue, New York, NY 10016, USA | Bereitstellung der LLM-Inferenz (Chat, Vision, Embeddings), der Audio-Verarbeitung (Speech-to-Text und Text-to-Speech) sowie der Bild-Verarbeitung und -Generierung. | Europäische Union (In-Region-Routing über `eu.openrouter.ai`). | Für Schweizer Orgs bleibt das Plattform-Hosting vollständig in der Schweiz. Der KI-Auftragsverarbeiter bietet keine Schweizer Region an; diese Aufrufe werden in der EU/im EWR verarbeitet — alle EU-/EWR-Staaten stehen auf der Staatenliste des Bundesrats nach Art. 16 FADP, die Übermittlung erfordert keine zusätzlichen Garantien. Zwei Hinweise zum KI-Auftragsverarbeiter (OpenRouter): er wird nur eingesetzt, wenn eine KI-Funktion einen Aufruf an ihn routet — eine Org, die weder LLM-Inferenz, Audio noch Bild-Funktionen nutzt, sendet ihm keine Daten. Modell-Anbieter, die über OpenRouter erreichbar sind (Anthropic, Google, Meta, Mistral, OpenAI usw.), sind Upstream-Anbieter von OpenRouter und keine direkten Auftragsverarbeiter von Tale — die Standard-Audio-Modelle (Whisper für Speech-to-Text, gpt-4o-mini-tts für Text-to-Speech) sind auf diesem Weg erreichte OpenAI-Modelle. Sie unterliegen den eigenen Vertragsbedingungen von OpenRouter; das In-Region-Routing beschränkt jeden Aufruf auf Anbieter-Endpunkte innerhalb der EU. ## Zertifizierungen und Trust-Seiten Jeder Auftragsverarbeiter führt eigene Sicherheitszertifizierungen und veröffentlicht sie auf seiner Trust-Seite: - **Exoscale (Akenes SA)** — ISO/IEC 27001:2022, ISO/IEC 27017, ISO/IEC 27018, SOC 2 Type II, PCI DSS v4.0, HDS, BSI C5, TISAX. Trust-Seite: [exoscale.com/compliance](https://www.exoscale.com/compliance/). - **OpenRouter, Inc.** — SOC 2; Nachweise über das zugangsbeschränkte Trust-Portal [trust.openrouter.ai](https://trust.openrouter.ai). Für Übermittlungen außerhalb der EU/des EWR gelten EU-Standardvertragsklauseln. ## Umfang der Verarbeitung Für jeden Auftragsverarbeiter: - **Exoscale (Akenes SA)** betreibt die Tale-Cloud-Middleware, den Anwendungs-State und die unterstützende Infrastruktur auf VMs und Container-Infrastruktur in der von deiner Org gewählten Region (Schweiz: Zürich mit Disaster-Recovery in Genf; EU: Frankfurt). Verschlüsselung at rest stellt Exoscales Storage-Schicht bereit. - **OpenRouter** verarbeitet Prompts und Antworten des jeweiligen LLM-Aufrufs (Chat, Vision, Embeddings), Audio-Payloads für Speech-to-Text und den Texteingang für Text-to-Speech sowie Bild-Prompts und generierte Bilder. Die Daten gehen über das In-Region-Routing von OpenRouter (`eu.openrouter.ai`) und werden auf Tales Seite nicht als separate Kopie gespeichert. ## Unter-Auftragsverarbeiter Jeder Auftragsverarbeiter oben beauftragt eigene Auftragsverarbeiter (Cloud-Hosting, CDN, Secret-Stores). Ihre Listen sind öffentlich und von der Trust-Seite jedes Anbieters verlinkt; Tale verfolgt wesentliche Änderungen an den Upstream-Listen über denselben 30-Tage-Hinweis-Mechanismus. ## Self-hosted: was sich ändert Wenn du Tale auf eigener Infrastruktur betreibst, sind die einzigen Daten, die Tale in deinem Auftrag verarbeitet, der Support- und Update-Verkehr, dem du zustimmst (Image-Pulls aus der Registry, optionale Telemetrie, Support-Tickets). Die Hosting- und Modell-Anbieter in der Tabelle oben werden von dir betrieben, nicht von Tale; die Auftragsverarbeiter-Liste deines Deployments ist der Stack, den du zusammenstellst. ## Wo das hingehört Auftragsverarbeiter sind das Anbieter-Inventar; die [Auftragsverarbeitungsvereinbarung](https://tale.dev/de/legal/data-processing-agreement) ist der Vertrag, unter dem sie operieren (Anhang A ist die kanonische Liste); die [Datenschutzerklärung](/de/legal/privacy) ist die nutzerseitige Erklärung; [Vertrauen und Compliance](/de/cloud/trust-and-compliance) ist der operative Beleg. Ein Auditor will die vier meist zusammen — die Anbieterliste, den Vertrag, die Erklärung und die Kontrollen — daher sind die verlinkten Seiten wechselseitig konsistent und werden in derselben Änderung aktualisiert. # Datenschutzerklärung Source: https://tale.dev/docs/de/legal/privacy Diese Erklärung beschreibt, wie Tale personenbezogene Daten verarbeitet, wenn du Tale Cloud, die Docs-Seite, die Marketing-Seite oder die Features im Produkt nutzt. Die Form ist dieselbe, ob du Endnutzer, Org-Admin oder Besucher der Docs bist — verschiedene Oberflächen erheben verschiedene Daten, und jede wird unten benannt. Die Erklärung gilt für Tale Cloud; selbst gehostete Instanzen werden von der Organisation betrieben, die sie betreibt, und Verantwortlicher ist diese Organisation, nicht Tale. Lies das, wenn du wissen willst, was Tale über dich speichert, warum, und wie du es entfernen kannst. Komm zurück, wenn sich die Erklärung ändert — wesentliche Änderungen werden auf der Status-Page angekündigt und an Org-Inhaber per E-Mail geschickt. ## Was wir erheben Drei Eimer an Daten existieren, jeder mit eigener Aufbewahrungsregel: - **Konto-Daten.** Name, E-Mail, Organisation, Rolle und die Credentials, mit denen du dich anmeldest. Nötig, um den Dienst zu betreiben. - **Produkt-Daten.** Alles, was du ins Produkt steckst — Agents, Workflows, Dokumente, Konversationen, Knowledge-Einträge, Integration-Credentials. Gespeichert, solange die Parent-Org existiert; gelöscht beim Org-Löschen oder über den Datenauskunfts-Workflow. - **Betriebs-Daten.** Server-Logs, Audit-Pfade, Support-Ticket-Inhalte, Performance-Metriken. An dein Konto oder deine Org gebunden, solange die Daten für Sicherheit, Debugging und Compliance nützlich sind — typisch bis zu 90 Tage für Logs und unbefristet für Audit-Pfade. Wir verkaufen keine personenbezogenen Daten. Wir nutzen Produkt-Daten nicht, um Modelle zu trainieren — deine Konversationen und Dokumente sind in keinem Modell-Trainingssatz, weder unserem noch dem eines Anbieters, ausser wo du ein Feature ausdrücklich aktiviert hast, das das verlangt, und der Einwilligungs-Prompt bestätigt wurde. ## Warum wir es erheben Die rechtliche Grundlage für jeden Eimer ist eine von: - **Vertragsnotwendigkeit.** Konto-Daten und die Produkt-Daten, die du anlegst, existieren, weil du uns gebeten hast, den Dienst bereitzustellen. Wir können die Plattform ohne sie nicht betreiben. - **Berechtigtes Interesse.** Betriebs-Daten werden erhoben, um die Plattform sicher zu halten, Ausfälle zu debuggen und vertragliche SLAs zu erfüllen. - **Einwilligung.** Marketing-Kommunikation, Analytik auf der Marketing-Seite und jedes Feature, das Daten über den Vertrag hinaus verarbeitet, sind einwilligungsbasiert — opt-in, widerrufbar und protokolliert. Die Aufschlüsselung der Rechtsgrundlage pro Datenkategorie steht im Auftragsverarbeitungs-Vertrag, der Enterprise-Kunden auf Anfrage zur Verfügung steht. ## Wie lange wir es aufbewahren | Daten | Aufbewahrung | | --------------------- | ------------------------------------------------------------------------------------ | | Konto-Daten | Lebensdauer der Org plus 30 Tage nach Löschung | | Produkt-Daten | Lebensdauer der Org; sofortige Löschung bei Org-Löschen | | Dokumente und Uploads | Lebensdauer des Parent-Datensatzes; soft-gelöschte Datensätze nach 30 Tagen gepurged | | Server-Logs | 90 Tage | | Audit-Logs | Org-konfigurierbarer Boden; Standard 365 Tage, keine Obergrenze | | Backups | 30 Tage, verschlüsselt at rest | Löschungen folgen dem dokumentierten Datenauskunfts-Workflow im Produkt — siehe die In-Product-Governance-Seite für die Betreiber-Oberfläche. ## Auftragsverarbeiter Tale Cloud nutzt eine kleine Anzahl Dritter, um den Dienst zu liefern. Jeder ist auf der [Auftragsverarbeiter-Seite](/de/legal/subprocessors) benannt, lokalisiert und im Umfang beschrieben. Wesentliche Änderungen an der Auftragsverarbeiter-Liste werden 30 Tage vor Wirksamwerden angekündigt; Org-Inhaber können über den Support widersprechen und den Vertrag kündigen, wenn der neue Auftragsverarbeiter nicht akzeptabel ist. ## Deine Rechte Du hast die Rechte aus der DSGVO (und die entsprechenden FADP-Rechte für Schweizer Betroffene): Auskunft, Berichtigung, Löschung, Einschränkung, Datenübertragbarkeit und Widerspruch. Die Mechanik: - **Auskunft und Übertragbarkeit.** Exportier deine Daten aus dem Produkt oder über die API; Roh-Exporte org-bezogener Daten sind auf Anfrage verfügbar. - **Berichtigung.** Bearbeite Konto-Daten und Produkt-Daten im Produkt. Für Daten, die du nicht erreichst (Server-Logs, Audit-Einträge mit deiner User-ID), reich eine Anfrage über den Support ein. - **Löschung.** Nutz den Datenauskunfts-Workflow unter **Einstellungen > Governance > Datenauskunfts-Anfragen**. Die Löschung erreicht jeden Dienst, der die Daten hält, einschliesslich Backups via Schlüsselzerstörung. - **Einschränkung und Widerspruch.** Reich über den Support ein; Tale bestätigt innerhalb von fünf Werktagen. Kontakt: `privacy@tale.dev`. Für Beschwerden ist die Aufsichtsbehörde die Datenschutzbehörde des Landes, in dem du wohnst. ## Wo das hingehört Datenschutz ist der Datenverarbeitungs-Vertrag; [Vertrauen und Compliance](/de/cloud/trust-and-compliance) ist der operative Beleg dahinter. Wenn du wissen willst, welche Dritten deine Daten berühren, ist [Auftragsverarbeiter](/de/legal/subprocessors) die Liste; wenn du selbst hostest, verlassen die Daten deine Infrastruktur nicht, und diese Erklärung gilt nur für deine Nutzung der eigenen Oberflächen von Tale (der Docs- und Marketing-Seiten). # Sous-traitants ultérieurs Source: https://tale.dev/docs/fr/legal/subprocessors Un sous-traitant ultérieur est un tiers que Tale engage pour traiter les données personnelles des clients pour son compte. La liste ci-dessous couvre Tale Cloud ; les opérateurs auto-hébergés contrôlent leur propre infrastructure et la liste de sous-traitants pour ces déploiements est celle des fournisseurs que tu choisis. Les ajouts substantiels sont annoncés 30 jours à l’avance et les Propriétaires d’org sont avertis par courriel. Lis ceci quand un auditeur demande qui d’autre touche tes données. Reviens-y quand une revue d’achats a besoin de la liste actuelle de fournisseurs et de la localisation de chacun. Cette page reprend l’**Annexe A** de l’[Accord de traitement des données](https://tale.dev/fr/legal/data-processing-agreement) — les deux sont mis à jour dans le même changement. Les endpoints et flux de données de la plateforme Tale elle-même sont décrits dans la [documentation API](https://demo.tale.dev/docs) publique. ## Aucune utilisation des données du client pour l’entraînement de modèles Tale n’utilise pas les données du client — prompts, entrées, sorties, embeddings, audio, images ou artefacts dérivés — pour entraîner, ajuster ou améliorer un modèle d’IA. Chaque sous-traitant ultérieur d’IA listé ci-dessous est contractuellement tenu, via ses conditions Enterprise ou API avec Tale, à la même chose. Une dérogation n’est possible que par un accord opt-in écrit séparé signé par les deux parties ; l’usage continu des services, des interrupteurs dans le produit ou un consentement implicite ne suffisent pas. La clause contraignante figure à l’[Accord de traitement des données § 5](https://tale.dev/fr/legal/data-processing-agreement#5-traitement-par-ia--aucune-utilisation-pour-lentrainement-ou-lamelioration). ## Sous-traitants ultérieurs actuels Chaque nom renvoie au DPA public du fournisseur (ou aux conditions équivalentes). Les certifications et pages de confiance figurent dans la section suivante. L’hébergement de la plateforme suit la résidence de données choisie par ton org : le premier tableau s’applique aux orgs de l’UE/EEE, le second aux orgs suisses. Les appels IA (inférence LLM, traitement audio et traitement d’images) sont traités dans l’UE/EEE pour toutes les orgs — aucun sous-traitant ultérieur d’IA engagé par Tale n’opère de région suisse, et aucun de ces appels n’est traité dans des pays tiers comme les États-Unis. ### Orgs de l’UE/EEE | Sous-traitant ultérieur (entité juridique) | Adresse du siège | Nature de la prestation | Lieu du traitement | | ----------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | [Akenes SA (Exoscale)](https://www.exoscale.com/dpa/) | Boulevard de Grancy 19A, 1006 Lausanne, Suisse | Infrastructure cloud (centre de données) : hébergement de la plateforme Tale Cloud — VM, runtime conteneurs, base de données et stockage. | Allemagne (région de Francfort). | | [OpenRouter, Inc.](https://openrouter.ai/privacy) | 169 Madison Avenue, New York, NY 10016, États-Unis | Inférence LLM (chat, vision, embeddings), traitement audio (Speech-to-Text et Text-to-Speech) ainsi que traitement et génération d’images. | Union européenne (routage in-region via `eu.openrouter.ai` : prompts et réponses traités exclusivement dans l’UE). | ### Orgs suisses | Sous-traitant ultérieur (entité juridique) | Adresse du siège | Nature de la prestation | Lieu du traitement | | ----------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | | [Akenes SA (Exoscale)](https://www.exoscale.com/dpa/) | Boulevard de Grancy 19A, 1006 Lausanne, Suisse | Infrastructure cloud (centre de données) : hébergement de la plateforme Tale Cloud — VM, runtime conteneurs, base de données et stockage. | Suisse (Zurich ; réplique de reprise après sinistre à Genève). | | [OpenRouter, Inc.](https://openrouter.ai/privacy) | 169 Madison Avenue, New York, NY 10016, États-Unis | Inférence LLM (chat, vision, embeddings), traitement audio (Speech-to-Text et Text-to-Speech) ainsi que traitement et génération d’images. | Union européenne (routage in-region via `eu.openrouter.ai`). | Pour les orgs suisses, l’hébergement de la plateforme reste intégralement en Suisse. Le sous-traitant ultérieur d’IA n’offre pas de région suisse ; ces appels sont traités dans l’UE/EEE — tous les pays de l’UE/EEE figurent sur la liste d’adéquation du Conseil fédéral au sens de l’art. 16 LPD, le transfert n’exige donc aucune garantie supplémentaire. Deux remarques sur le sous-traitant ultérieur d’IA (OpenRouter) : il n’est engagé que lorsqu’une fonctionnalité d’IA route un appel vers lui — une org qui n’utilise ni l’inférence LLM, ni l’audio, ni les fonctionnalités d’images ne lui envoie aucune donnée. Les fournisseurs de modèles accessibles via OpenRouter (Anthropic, Google, Meta, Mistral, OpenAI, etc.) sont des fournisseurs amont d’OpenRouter, pas des sous-traitants ultérieurs directs de Tale — les modèles audio par défaut (Whisper pour le Speech-to-Text, gpt-4o-mini-tts pour le Text-to-Speech) sont des modèles OpenAI atteints de cette façon. Ils opèrent sous les conditions contractuelles propres à OpenRouter ; le routage in-region limite chaque appel aux endpoints de fournisseurs situés dans l’UE. ## Certifications et pages de confiance Chaque sous-traitant ultérieur détient ses propres certifications de sécurité et les publie sur sa page de confiance : - **Exoscale (Akenes SA)** — ISO/IEC 27001:2022, ISO/IEC 27017, ISO/IEC 27018, SOC 2 Type II, PCI DSS v4.0, HDS, BSI C5, TISAX. Page de confiance : [exoscale.com/compliance](https://www.exoscale.com/compliance/). - **OpenRouter, Inc.** — SOC 2 ; preuves disponibles via le portail de confiance à accès restreint [trust.openrouter.ai](https://trust.openrouter.ai). Les clauses contractuelles types de l’UE s’appliquent aux transferts hors UE/EEE. ## Périmètre du traitement Pour chaque sous-traitant ultérieur : - **Exoscale (Akenes SA)** exécute la middleware Tale Cloud, l’état applicatif et l’infrastructure de support sur des VM et une infrastructure conteneurs dans la région choisie par ton org (Suisse : Zurich avec reprise après sinistre à Genève ; UE : Francfort). Le chiffrement au repos est fourni par la couche de stockage d’Exoscale. - **OpenRouter** traite les prompts et réponses de l’appel LLM concerné (chat, vision, embeddings), les payloads audio pour le Speech-to-Text et l’entrée texte pour le Text-to-Speech, ainsi que les prompts d’images et les images générées. Les données partent via le routage in-region d’OpenRouter (`eu.openrouter.ai`) et ne sont pas conservées côté Tale comme copie séparée. ## Sous-sous-traitants Chaque sous-traitant ultérieur ci-dessus engage ses propres sous-traitants (hébergement cloud, CDN, magasins de secrets). Leurs listes sont publiques et liées depuis la page de confiance de chaque fournisseur ; Tale suit les changements substantiels aux listes amont via le même mécanisme de préavis de 30 jours. ## Auto-hébergé : ce qui change Si tu fais tourner Tale sur ta propre infrastructure, les seules données que Tale traite pour ton compte sont le trafic de support et de mise à jour auquel tu consens (tirages d’images depuis le registre, télémétrie optionnelle, tickets de support). Les fournisseurs d’hébergement et de modèles dans le tableau ci-dessus sont opérés par toi, pas par Tale ; la liste de sous-traitants de ton déploiement est la stack que tu assembles. ## Où cela s’inscrit Les sous-traitants ultérieurs sont l’inventaire des fournisseurs ; l’[Accord de traitement des données](https://tale.dev/fr/legal/data-processing-agreement) est le contrat sous lequel ils opèrent (l’Annexe A est la liste de référence) ; la [Politique de confidentialité](/fr/legal/privacy) est la politique côté utilisateur ; [Confiance et conformité](/fr/cloud/trust-and-compliance) est la preuve opérationnelle. Un auditeur veut généralement les quatre ensemble — la liste de fournisseurs, le contrat, la politique et les contrôles — donc les pages liées sont mutuellement cohérentes et mises à jour dans le même changement. # Politique de confidentialité Source: https://tale.dev/docs/fr/legal/privacy Cette politique décrit comment Tale traite les données personnelles quand tu utilises Tale Cloud, le site de docs, le site marketing ou les fonctionnalités dans le produit. La forme est la même que tu sois utilisateur final, admin d'org ou visiteur lisant les docs — des surfaces différentes collectent des données différentes, et chacune est nommée plus bas. La politique s'applique à Tale Cloud ; les instances auto-hébergées sont opérées par l'organisation qui les fait tourner, et le responsable de traitement est cette organisation, pas Tale. Lis ceci quand tu veux savoir ce que Tale conserve à ton sujet, pourquoi, et comment l'enlever. Reviens-y quand la politique change — les changements substantiels sont annoncés sur la page de statut et envoyés par courriel aux Propriétaires d'org. ## Ce que nous collectons Trois seaux de données existent, chacun avec sa propre règle de conservation : - **Données de compte.** Nom, courriel, organisation, rôle et identifiants avec lesquels tu te connectes. Nécessaires pour opérer le service. - **Données produit.** Tout ce que tu mets dans le produit — agents, workflows, documents, conversations, entrées de base de connaissances, identifiants d'intégration. Stockées tant que l'org parente existe ; supprimées à la suppression de l'org ou via le flux de demande de la personne concernée. - **Données opérationnelles.** Journaux serveur, pistes d'audit, contenu des tickets de support, métriques de performance. Liées à ton compte ou à ton org tant que la donnée sert à la sécurité, au débogage et à la conformité — typiquement jusqu'à 90 jours pour les journaux et indéfiniment pour les pistes d'audit. Nous ne vendons pas de données personnelles. Nous n'utilisons pas les données produit pour entraîner des modèles — tes conversations et tes documents ne font partie d'aucun jeu d'entraînement de modèle, ni le nôtre ni celui d'aucun fournisseur, sauf quand tu as explicitement activé une fonctionnalité qui le requiert et confirmé l'invite de consentement. ## Pourquoi nous le collectons La base légale de chaque seau est l'une de : - **Nécessité contractuelle.** Les données de compte et les données produit que tu crées existent parce que tu nous as demandé de fournir le service. Nous ne pouvons pas opérer la plateforme sans elles. - **Intérêt légitime.** Les données opérationnelles sont collectées pour garder la plateforme sûre, déboguer les pannes et respecter les SLA contractuels. - **Consentement.** Les communications marketing, l'analytique sur le site marketing et toute fonctionnalité qui traite des données au-delà du contrat sont fondées sur le consentement — opt-in, révocable et tracé. La ventilation de la base légale par catégorie de donnée vit dans l'Accord de Traitement de Données disponible aux clients entreprise sur demande. ## Combien de temps nous le gardons | Donnée | Conservation | | --------------------------- | ------------------------------------------------------------------------------- | | Données de compte | Vie de l'org plus 30 jours après suppression | | Données produit | Vie de l'org ; effacement immédiat à la suppression de l'org | | Documents et téléversements | Vie de l'enregistrement parent ; enregistrements soft-deleted purgés à 30 jours | | Journaux serveur | 90 jours | | Journaux d'audit | Plancher configurable par l'org ; défaut 365 jours, pas de plafond | | Sauvegardes | 30 jours, chiffrées au repos | L'effacement suit le flux de demande de la personne concernée documenté dans le produit — voir la page gouvernance dans le produit pour la surface opérateur. ## Sous-traitants ultérieurs Tale Cloud utilise un petit nombre de tiers pour livrer le service. Chacun est nommé, localisé et périmétré sur la page [Sous-traitants ultérieurs](/fr/legal/subprocessors). Les changements substantiels à la liste des sous-traitants sont annoncés 30 jours avant prise d'effet ; les Propriétaires d'org peuvent s'opposer via le support et faire résilier le contrat si le nouveau sous-traitant n'est pas acceptable. ## Tes droits Tu as les droits accordés par le RGPD (et les droits FADP équivalents pour les personnes concernées suisses) : accès, rectification, effacement, restriction, portabilité et opposition. La mécanique : - **Accès et portabilité.** Exporte tes données depuis le produit ou via l'API ; les exports bruts des données au périmètre org sont disponibles sur demande. - **Rectification.** Édite les données de compte et les données produit depuis le produit. Pour les données que tu n'atteins pas (journaux serveur, entrées d'audit avec ton ID utilisateur), soumets une demande via le support. - **Effacement.** Utilise le flux de demande de la personne concernée sous **Paramètres > Gouvernance > Demandes des personnes concernées**. L'effacement traverse chaque service qui détient la donnée, y compris les sauvegardes via destruction de clé. - **Restriction et opposition.** Soumets via le support ; Tale accuse réception sous cinq jours ouvrés. Contact : `privacy@tale.dev`. Pour les plaintes, l'autorité de contrôle est l'autorité de protection des données du pays où tu résides. ## Où cela s'inscrit La confidentialité est le contrat de traitement des données ; [Confiance et conformité](/fr/cloud/trust-and-compliance) est la preuve opérationnelle qui en découle. Si tu veux savoir quels tiers touchent tes données, [Sous-traitants ultérieurs](/fr/legal/subprocessors) est la liste ; si tu opères en auto-hébergé, la donnée ne quitte pas ton infrastructure, et cette politique ne s'applique qu'à ton usage des surfaces propres à Tale (les sites de docs et marketing).