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

# Create and manage agents

> Configure an agent’s identity, models, tools, and conversation connections.

Formation starts with no agents. Create one in the dashboard, give it a model and a
profile, then connect the places where people will talk to it. Agents and their
settings live in PostgreSQL and can also be managed through the [Operator
API](https://docs.formation.texturehq.com/operator-api.md).

Your operator login and the agent's identity are separate. An operator manages
Formation; an agent participates in conversations using its own accounts.

## Before you start

* Run Formation with a working database and `MESH_AGENT_MASTER_KEY`. Keep the master
  key outside the database and back it up securely; see [Secrets and
  recovery](https://docs.formation.texturehq.com/secrets-and-recovery.md).
* Set `PUBLIC_URL` to the stable HTTPS address people and providers will use.
  Slack, Telegram and phone webhooks need a reachable deployment. Configure DNS
  and TLS before registering their webhooks.
* Have access to a model provider, or ask an owner to configure **Instance model
  defaults**. Supported providers are OpenRouter, Ramp Router, and OpenAI or an
  OpenAI-compatible server. [Model providers](https://docs.formation.texturehq.com/connectors/model.md) explains the
  choices.

## Set up the first agent

1. **Sign in as an operator.** A fresh installation using local authentication
   asks you to create the first administrator. That account is an owner. Owners
   can invite other owners or give an agent operator access to selected agents.
   Deployments using [external authentication](https://docs.formation.texturehq.com/external-authentication.md) use
   their configured sign-in flow instead.
2. **Create and name the agent.** Enter a display name and slug. Formation saves a
   draft so you can resume setup after a reload.
3. **Connect a model.** If instance defaults are configured, the wizard uses
   their provider, billing credential and model assignments. Choose **Customize
   models** for a different provider or an agent-specific key. Otherwise connect
   a provider and select a primary model. Fast and heartbeat are optional roles;
   heartbeat falls back to fast, and fast to primary.
4. **Describe its job.** Draft and review a profile or write one yourself. Guided setup prepares memory defaults from the selected provider without a separate configuration step. Picture customization is optional. Use **Advanced setup** for explicit memory, tools and external chat setup.
5. **Try a first task inside Formation.** The native conversation needs no Slack or Telegram account. Send a message, confirm the delivered reply, and try one tool action. The first-task checklist reads actual runtime results; a healthy instance or a saved connection is not a completed task.
6. **Add tools and external chat when needed.** The agent overview opens native **Chat**. Tools connects this agent’s own service accounts. Connections adds Slack, Telegram or phone. Neither is required to start a conversation in Formation. For Slack, invite the agent to a channel before mentioning it there.

Native chat is an operator conversation, scoped to that operator and agent. It is retained in the normal conversation graph and a durable delivery mailbox. Operators who already have inspection access to the agent can inspect its history. It does not create or inherit an external acting identity. Accepted messages and replies survive refresh; uncertain sends reuse their request ID. The chat view shows the latest 100 entries; captured earlier history remains available in Conversations.

Repeat this flow for additional agents. Each has its own perspective, profile,
connections, memory and work. You can add more connector installations to an
existing agent.

## Choose where people can reach the agent

| Connector | Setup guide | What to expect |
| - | - | - |
| Slack | [Automatic Slack setup](https://docs.formation.texturehq.com/slack-automatic-setup.md) | Create a separate app for the agent, or connect an existing app manually. |
| Telegram | [Telegram](https://docs.formation.texturehq.com/connectors/telegram.md) | Connect the agent's bot token and register its webhook. |
| Phone | [Phone](https://docs.formation.texturehq.com/connectors/phone.md) | Connect an SMS-capable number and choose who may text it. |

## Add tools during or after setup

An agent's **Tools** page manages native integrations, remote MCP accounts, web
access and coding tools. Follow [Tool setup](https://docs.formation.texturehq.com/runtime/capability-setup.md).
Model billing and execution-provider credentials may be inherited infrastructure;
external acting accounts belong to the agent. A second token for the same external
account does not create a distinct acting identity.

Then configure optional features as needed: [automatic model
selection](https://docs.formation.texturehq.com/runtime/adaptive-model-routing.md) (on by default for new agents),
[Dreaming](https://docs.formation.texturehq.com/runtime/dreaming.md), [commitments](https://docs.formation.texturehq.com/runtime/commitments.md), and the
[agent vault](https://docs.formation.texturehq.com/runtime/agent-vault.md).

## Change a hostname or repair a connection

Changing `PUBLIC_URL` does not update webhook addresses already stored at a
provider. For a managed Slack app, use **Update Slack configuration** on each
connection. For a manual Slack app, update its Event Subscriptions request URL
and reverify it; the dashboard shows the expected URL. Other connectors must
also have their provider-side webhook registration updated.

A manual Slack URL challenge can return `401` before its connector credentials
have been saved. Save the connector and retry verification. For missing Slack
permissions, use **Check permissions** and **Update Slack permissions** on a
managed app; manual apps require a scope update and reinstall in Slack.

Runtime registry reload applies to the process handling the change. Database
persistence and durable work queues alone do not establish multi-replica
configuration propagation; operate within your deployment's supported topology.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.