Skip to main content
Assistants are the primary AI actors in the Feather platform. An assistant bundles an agent (a persona and system prompt) with an optional workflow (a structured conversation graph) as a single unit. Every interaction your end users have with Feather flows through an assistant.

​
What is an assistant?

An assistant combines identity with capability. At its core, an assistant carries:
  • A persona — a name, description, and persona string that shape how the assistant presents itself.
  • A system prompt — instructions that shape the assistant’s tone, role, and behavior.
  • Knowledge bases — indexed document collections the assistant retrieves from at runtime (knowledge_base_refs).
  • Tools — API, integration, utility, or knowledge-base tools the assistant can invoke (tool_refs).
  • Policies — guardrails that run at defined enforcement points to control what the assistant says and does (policy_refs).
  • A workflow — an optional graph that drives multi-step, structured conversations. Creating an assistant provisions a bound workflow automatically; you enable it per revision with workflow_enabled.
Because assistants run in production alongside real user data, Feather uses a revision model to keep changes auditable and rollbacks safe.
The API resource is /v1/assistants. For historical reasons the path variable is spelled {agent_id} — for example GET /v1/assistants/{agent_id}. The two refer to the same thing.

​
The revision model

Every assistant has two layers of identity: When you create an assistant, Feather provisions an initial revision automatically — but the assistant starts inactive (active_revision_id is null). You configure a revision, then activate it to make the assistant serve traffic.
There is no “publish” step. You make a revision live by activating it: POST /v1/assistants/{agent_id}/revisions/{revision_id}/activate. Activation simply points the assistant’s active_revision_id at that revision.
A revision has no separate status field — a revision is “active” if and only if the assistant’s active_revision_id points to it. All other revisions are editable configuration you can iterate on and activate later.

​
Revision lifecycle

1

Create a revision

Call POST /v1/assistants/{agent_id}/revisions. Pass based_on_revision_id to branch from an existing revision, or omit it to start fresh.
2

Configure the revision

Call PATCH /v1/assistants/{agent_id}/revisions/{revision_id} to set system_prompt, attach knowledge_base_refs and tool_refs, and set model_settings, channel_specific_config, and platform_tools. Attach policies with PUT /v1/assistants/revisions/{revision_id}/policies.
3

Activate the revision

Call POST /v1/assistants/{agent_id}/revisions/{revision_id}/activate. Feather updates the assistant’s active_revision_id. New conversations now use this revision.
4

Iterate safely

To change behavior, create another revision, configure it, and activate it. Previous revisions remain available for rollback or audit — activate any of them to roll back.
Conversations pin the revision that was active when they were created (see How assistants map to conversations), so activating a new revision never disrupts in-flight sessions.

​
Key fields

​
channel_specific_config

Some behaviors need to differ by channel. The channel_specific_config field accepts a map keyed by channel — chat, sms, voice, or email — letting you override the prompt, first-speaking behavior, and warm-transfer settings per channel without creating a separate assistant.
Use channel_specific_config to add a channel-specific instruction addendum rather than duplicating an entire system prompt. For example, append "Keep all responses under 160 characters." for the sms channel only.

​
Platform tools

Beyond the custom tools you attach via tool_refs, Feather provides built-in platform tools that any assistant can enable with no extra configuration. Fetch the catalog with GET /v1/assistants/platform-tools/catalog and enable tools per revision via the platform_tools field. The assistant-scoped catalog contains three tools:

transfer_call

Transfers the current call to another destination. Terminal — it ends the assistant’s turn.

request_human_handoff

Hands the conversation off to a human. Sets the conversation to waiting_for_human.

end_session

Gracefully closes the conversation and ends the session.
Platform tools are terminal — they conclude the current turn. Additional flow-control tools (such as advancing a workflow step) exist inside workflow graphs but are not assistant-enableable and do not appear in the catalog.

​
How assistants map to conversations

When you create a conversation (POST /v1/conversations), you set assistant_id. Feather resolves the assistant’s active revision at that moment and pins it to the conversation as assistant_revision_id. This means:
  • Subsequent changes to the assistant or its revisions do not affect the in-flight conversation.
  • Every turn in the conversation runs against the same pinned revision.
  • You can pin a specific revision explicitly by passing assistant_revision_id on create.
This pinning is what makes Feather safe for long-running sessions like multi-day email threads or complex support escalations.
Bind a conversation to either a single assistant (assistant_id) or a team (team_id + team_revision_id), never both.

​
Teams

Group multiple assistants into a team to enable multi-agent routing. A team revision defines a routing mode, a set of member assistants, and a required fallback member. Feather supports two routing modes:

supervisor

A supervisor evaluates each incoming turn and delegates to the most appropriate member assistant. Ideal when you have specialized assistants (billing, technical, general) and want intelligent routing.

swarm

Members hand off directly to one another as the conversation evolves, up to swarm_max_hops. Useful for collaborative flows where control passes between peers.
Each team member references an assistant_id (and optionally pins an assistant_revision_id). Teams version through revisions too, but you make a team revision live with POST /v1/teams/{team_id}/set-active-revision. A conversation can bind to a team instead of a single assistant — Feather handles routing internally.

​
Next steps

Build your first assistant

A step-by-step guide to creating an assistant, configuring a revision, and running your first conversation.

Assistants API reference

Full reference for assistant and revision endpoints, including request schemas and response examples.