Agents and Chat

Create AI agents that can use your workflows as tools and hold conversations.

Overview

Agents combine:

• A system prompt defining personality/behavior
• Access to workflows as callable tools
• Optional knowledge sources for RAG
• Conversation history management

Creating an Agent

1. Navigate to Agents in the sidebar

2. Click Create Agent

3. Configure:

   • Name: Display name for the agent
   • System Prompt: Instructions for the AI
   • Access Level: Public, Authenticated, or Role-based

4. Assign tools (workflows) the agent can call

5. Optionally add knowledge sources

Agent Access Levels

Level	Description
Public	Anyone can chat (no auth required)
Authenticated	Logged-in users only
Role-based	Users with assigned roles only

Adding Tools

Mark workflows as tools to make them callable by agents:

from bifrost import workflow

@workflow(
    is_tool=True,
    tool_description="Look up a customer by email address"
)
async def lookup_customer(email: str):
    # ... lookup logic
    return {"name": "John Doe", "account": "12345"}

The tool_description helps the agent understand when to use the tool.

Knowledge Sources

Attach knowledge namespaces for RAG:

1. In agent settings, add Knowledge Sources
2. Select namespaces (e.g., “faq”, “docs”)
3. Agent automatically searches these when answering

Chat API

Start conversations programmatically:

Create Conversation

import requests

response = requests.post(
    f"{api_url}/api/chat/conversations",
    json={"agent_id": "agent-123"},  # Optional
    headers={"Authorization": f"Bearer {token}"}
)
conversation_id = response.json()["id"]

Send Message

response = requests.post(
    f"{api_url}/api/chat/conversations/{conversation_id}/messages",
    json={"content": "Hello, I need help with my account."},
    headers={"Authorization": f"Bearer {token}"}
)

WebSocket Streaming

For real-time streaming responses:

const ws = new WebSocket(
    `wss://your-instance.com/api/chat/conversations/${conversationId}/stream`
);

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === "delta") {
        console.log(data.content);
    }
};

ws.send(JSON.stringify({ content: "How do I reset my password?" }));

@Mentions

Switch agents mid-conversation using @mentions:

User: @support-agent I need help with billing
AI: (responds as support-agent)

User: @tech-agent Can you check my server status?
AI: (switches to tech-agent)

Agent Delegation

Agents can delegate to other agents:

1. In agent settings, add Delegations
2. Select agents this one can hand off to
3. The AI decides when to delegate based on context

Tip

Delegation is useful for specialized agents - a general triage agent can delegate to billing, tech support, or sales agents.

Agentless Chat

Chat without a specific agent uses default routing:

response = requests.post(
    f"{api_url}/api/chat/conversations",
    json={},  # No agent_id
    headers={"Authorization": f"Bearer {token}"}
)

The system uses AI-based routing to select an appropriate agent or responds with a default system prompt.

Example: Support Agent

from bifrost import workflow

@workflow(
    is_tool=True,
    tool_description="Look up a support ticket by ID"
)
async def get_ticket(ticket_id: str):
    # Fetch ticket from your system
    return {"id": ticket_id, "status": "open", "subject": "..."}

@workflow(
    is_tool=True,
    tool_description="Update the status of a support ticket"
)
async def update_ticket(ticket_id: str, status: str, note: str = ""):
    # Update ticket
    return {"success": True}

Create an agent with these tools and a prompt like:

“You are a helpful support agent. Use the tools to look up and update tickets. Always confirm before making changes.”

The Coding Agent

The Coding Agent is a special system agent for creating and modifying Bifrost workflows using Claude. It provides AI-assisted development capabilities directly within the platform.

Characteristics

• System agent: Auto-created on platform startup, cannot be deleted
• Claude-powered: Uses the Claude Agent SDK with MCP tools
• Workspace access: Has full access to workspace files and system tools
• Development focus: Optimized for workflow creation and modification

System Tools

The Coding Agent has access to the following system tools:

Tool	Description
execute_workflow	Execute a workflow by name or ID
list_workflows	List all registered workflows
validate_workflow	Validate workflow Python syntax
get_workflow	Get workflow metadata
get_workflow_schema	Documentation about decorators
list_executions	List recent executions
get_execution	Get execution details and logs
list_integrations	List integrations and their status
list_forms	List all forms
get_form	Get form details
get_form_schema	Form structure documentation
validate_form_schema	Validate form JSON
search_knowledge	Search the knowledge base
read_file	Read a workspace file
write_file	Write a workspace file
list_files	List files and directories
delete_file	Delete a file or folder
search_files	Search for text patterns in files
create_folder	Create a new folder
create_form	Create a new form
update_form	Update an existing form

Making Workflows Available as Tools

Workflows can be exposed as tools for agents to call:

from bifrost import workflow

@workflow(
    is_tool=True,
    tool_description="Fetch customer data by email"
)
async def get_customer(email: str):
    """Look up customer information."""
    # ... implementation
    return {"name": "John Doe", "account": "12345"}

When is_tool=True:

1. The workflow appears in the platform’s tool list
2. Assign it to agents via the UI or API
3. The agent can then call the workflow as a tool during conversations

Tool Assignment

Tools are assigned to agents in two ways:

• System tools: Assigned via the system_tools array on the agent configuration
• Workflow tools: Assigned via the agent-tools relationship in the UI or API

The Coding Agent receives all system tools by default. Custom agents only receive the tools explicitly assigned to them.

Next Steps

• Using AI in Workflows - Direct AI completions
• Knowledge Bases - RAG setup
• MCP Server - External AI tool access