Create an AI agent with a system prompt, attach a knowledge base, add a custom tool, and bind it to a conversation — step by step.
Every Feather AI agent is made up of a few composable pieces: an agent record that holds metadata, one or more revisions that define its behavior (system prompt, tools, knowledge bases), and a pointer to the currently active revision that runs in production. This guide walks you through creating each piece from scratch — by the end you’ll have a fully configured agent ready to handle real conversations.
1
Create the agent
Start by registering a new agent in your organization. This creates the top-level agent record — no behavior is defined yet.
curl -X POST https://api-sandbox.featherhq.com/v1/agents \ -H "x-api-key: $FEATHER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Customer Support Bot", "description": "Helps customers with account questions" }'
A successful response returns the new agent object:
{ "id": "agt_01hx3k2mz9vbqwerty123456", "organization_id": "org_01hx0abc123def456ghi789", "name": "Customer Support Bot", "description": "Helps customers with account questions", "active_revision_id": null, "created_at": "2024-05-14T10:22:00Z"}
Note that active_revision_id is null — the agent won’t respond to conversations until you create and activate a revision.
2
Create a revision with a system prompt
A revision captures the agent’s complete configuration at a point in time. Create v1 now with a system prompt and a context variable that carries the customer’s name into every conversation.
curl -X POST https://api-sandbox.featherhq.com/v1/agents/agt_01hx3k2mz9vbqwerty123456/revisions \ -H "x-api-key: $FEATHER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "v1", "system_prompt": "You are a helpful customer support agent. Always be polite and concise. If you do not know the answer, say so.", "context_variables": [ { "name": "customer_name", "type": "string", "source": "derived" } ] }'
{ "id": "rev_01hx3k9pq7rstuv234567890", "agent_id": "agt_01hx3k2mz9vbqwerty123456", "name": "v1", "system_prompt": "You are a helpful customer support agent. Always be polite and concise. If you do not know the answer, say so.", "context_variables": [ { "name": "customer_name", "type": "string", "source": "derived" } ], "knowledge_base_refs": null, "tool_refs": null, "created_at": "2024-05-14T10:23:15Z"}
Save the revision id — you’ll need it in the steps ahead.
3
Create a knowledge base
Knowledge bases store the documents your agent can search at inference time. Create one for your product documentation now.
The knowledge base is empty for now. See Ingest Documents to populate it with files, text snippets, or external sources like Notion.
4
Attach the knowledge base to the revision
Update the revision to reference the knowledge base. The description inside knowledge_base_refs is used by the agent to decide when to query this source.
The endpoint returns the now-active revision object:
{ "id": "rev_01hx3k9pq7rstuv234567890", "agent_id": "agt_01hx3k2mz9vbqwerty123456", "name": "v1", "system_prompt": "You are a helpful customer support agent. Always be polite and concise. If you do not know the answer, say so.", "context_variables": [ { "name": "customer_name", "type": "string", "source": "derived" } ], "knowledge_base_refs": [ { "id": "kb_01hx4mno5pqrstuvwxyz0001", "description": "Product documentation for answering customer questions" } ], "tool_refs": null, "policies_enabled": true, "created_at": "2024-05-14T10:23:15Z", "updated_at": "2024-05-14T10:25:30Z"}
The agent’s active revision is now v1 — a subsequent GET /v1/agents/agt_01hx3k2mz9vbqwerty123456 would show active_revision_id pointing to this revision. Any future revisions you create won’t go live until you call this endpoint again.
6
Test with a conversation
Use the test-chat endpoint to spin up a sandboxed session without affecting production analytics or memory.Open a test session:
curl -X POST https://api-sandbox.featherhq.com/v1/v2/conversations/sess_01hx5test9876543210abcd/turns \ -H "x-api-key: $FEATHER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "user_message": "What features do you offer?" }'
{ "turn_id": "turn_01hx5abc123def456ghi789", "text": "Great question! Our platform offers real-time conversation management, AI-powered knowledge retrieval, custom tool integrations, and seamless human handoff. Is there a specific feature you'd like to know more about?", "session_status": "active", "message_seqs": [4, 5]}
Test sessions (session_type: test) are isolated — they do not sync conversation history to long-term memory, trigger post-session webhooks, or count toward production usage metrics. Use them freely during development.
curl -X POST https://api-sandbox.featherhq.com/v1/tools \ -H "x-api-key: $FEATHER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "lookup_order", "description": "Look up the status of a customer order by order ID.", "configuration": { "url": "https://api.yourstore.com/orders/{{order_id}}", "method": "GET", "headers": [ { "key": "Authorization", "value": "Bearer sk_live_your_store_api_key", "secure": true } ], "variables": [ { "name": "order_id", "description": "The order ID to look up", "type": "str", "required": true } ] } }'
{ "id": "tool_01hx6orderlookup12345678", "name": "lookup_order", "description": "Look up the status of a customer order by order ID.", "created_at": "2024-05-14T10:30:00Z"}
The agent will now automatically invoke lookup_order whenever a customer asks about a specific order. It extracts the order_id from the conversation, and that value is substituted into the request URL via the {{order_id}} placeholder.
You can attach multiple tools and knowledge bases to a single revision. The agent decides which resources to use based on the conversation context and the descriptions you provide on each reference.