Skip to main content
Agents are the primary AI actors in the Feather platform. Each agent represents an AI assistant with a defined persona, a system prompt, and a set of capabilities — including knowledge bases, tools, and policies. Every interaction your end users have with Feather flows through an agent.

​
What Is an Agent?

An agent combines identity with capability. At its core, an agent carries:
  • A persona — a human-readable name and description that surfaces in logs, dashboards, and handoff messages.
  • A system prompt — instructions that shape the agent’s tone, role, and behavior during a conversation.
  • Knowledge bases — indexed document collections the agent retrieves from at runtime.
  • Tools — external API calls or platform capabilities the agent can invoke.
  • Policies — guardrails that run at defined enforcement points to control what the agent says and does.
Because agents live in production environments alongside real user data, Feather enforces an immutable revision model to keep changes auditable and rollbacks safe.

​
The Revision Model

Every agent has two layers of identity:
LayerMutabilityPurpose
Agent recordMutableStores name, description, and a pointer to the active revision
RevisionImmutable once publishedStores system prompt, KB refs, tool refs, policy refs, and model settings
When you first create an agent, Feather creates a draft revision automatically. You iterate on that draft until you’re ready to publish. Once you call POST /v1/agents/revisions/{revision_id}/publish, the revision is frozen — its system_prompt, knowledge_base_refs, tool_refs, and policy_refs can no longer be changed. To update agent behavior, you create a new draft revision and publish that instead.
The agent’s active_revision_id field always points to the currently published revision. Any conversation started after a new revision is published will use the new behavior — existing conversations remain pinned to the revision that was active when they were created.

​
Revision lifecycle

1

Create a draft revision

Call POST /v1/agents/{agent_id}/revisions to create a new draft. The revision starts in draft status.
2

Configure the revision

Set the system_prompt, attach knowledge_base_refs, tool_refs, policy_refs, and model_settings on the draft. All fields remain editable at this stage.
3

Publish the revision

Call POST /v1/agents/revisions/{revision_id}/publish. The revision status moves to published and becomes immutable. Feather updates the agent’s active_revision_id automatically.
4

Create another draft when needed

When you need to update behavior, repeat the process. Previous revisions remain available for rollback or audit.

​
Key Fields

FieldTypeDescription
namestringDisplay name for the agent (e.g. "Support Bot")
descriptionstringInternal description of the agent’s purpose
active_revision_idstringPoints to the currently published revision
team_idstringOptional — the team this agent belongs to
FieldTypeDescription
system_promptstringCore instruction set for the agent’s LLM
knowledge_base_refsarrayIDs of knowledge bases the agent searches at runtime
tool_refsarrayIDs of tools the agent may call
policy_refsarrayIDs of policies enforced on this revision
model_settingsobjectLLM provider, model name, temperature, max tokens
channel_specific_configobjectPer-channel overrides (e.g. shorter responses on SMS)

​
channel_specific_config

Some behaviors need to differ by channel. For example, you might want a more concise response format for SMS than for API or email. The channel_specific_config field accepts a map keyed by channel type (api, sms, voice, email), letting you override system_prompt additions, response length hints, or enabled tool sets per channel without creating a separate agent.
Use channel_specific_config to add a channel-specific instruction addendum rather than duplicating entire system prompts. 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 a set of platform tools — built-in capabilities available to every agent with no additional configuration. Platform tools appear in the agent’s tool list at runtime and can be invoked like any other tool.

transfer_call

Transfers the current conversation to another agent or a human queue. Accepts a target agent ID or queue ID and an optional handoff message.

end_session

Gracefully closes the conversation, sets status to closed, and emits a configurable farewell message to the end user.

send_message

Sends a proactive message to the end user mid-turn, useful for streaming updates during long-running tool calls.

request_approval

Pauses the conversation and creates an approval request, surfacing it to a human reviewer before proceeding.
Platform tools count against your per-turn tool call limits. If your agent makes heavy use of custom tools, be mindful of combining them with frequent platform tool calls in the same turn.

​
How Agents Map to Conversations

When you create a conversation (via POST /v1/conversations), you specify an agent_id. Feather resolves the agent’s active_revision_id at that moment and pins it to the conversation. This means:
  • Subsequent changes to the agent or its revisions do not affect the in-flight conversation.
  • Every turn in the conversation runs against the same frozen revision.
  • You can inspect pinned_revision_id on the conversation object to see exactly which revision is active.
This pinning behavior is what makes Feather safe for long-running sessions like multi-day email threads or complex support escalations.

​
Teams

You can group multiple agents into a team to enable multi-agent routing. A team defines a routing strategy and a set of member agents. Feather supports two routing modes:

Supervisor routing

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

Swarm routing

All member agents are eligible to respond, and Feather selects the agent best suited to the current turn based on capability matching. Useful for load distribution across agents with similar roles.
Teams are configured separately and referenced by team_id on the agent record. A conversation can be assigned to a team rather than a specific agent — Feather handles routing internally and updates assigned_agent_id on the conversation object as routing decisions are made.

​
Next Steps

Build Your First Agent

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

Agents API Reference

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