Agents

What Are Agents

Agents are the core of Macha. An agent is an AI copilot configured with specific instructions, tools, and knowledge to help your team with a particular job. Think of each agent as a specialist — one might handle customer support tickets, another might look up order information, and a third might triage incoming requests.

Every agent has its own personality, capabilities, and access permissions. You control exactly what each agent can do by choosing its model, writing its instructions, and assigning the connectors and data sources it needs.

Creating a New Agent

Navigate to the Agents page and click "New Agent." You will see a configuration form with several sections.

Name

Give your agent a clear, descriptive name that reflects its purpose. For example: "Zendesk Support Agent," "Billing Specialist," or "Order Lookup Assistant." The name is visible to your team when they select an agent to chat with.

Instructions

Instructions are the system prompt that shapes how your agent behaves. This is the single most important part of agent configuration — it tells the AI who it is, how it should respond, and what rules to follow.

Model Selection

Macha supports multiple AI models from different providers. Each model has different strengths:

• OpenAI GPT-4o — Excellent all-around model with strong reasoning, tool use, and instruction following. Best choice for most workflows.
• OpenAI GPT-4o Mini — Faster and more cost-efficient. Good for simpler tasks where speed matters more than depth.
• Anthropic Claude — Strong at nuanced writing, careful reasoning, and following complex instructions. Great for tasks requiring attention to detail.
• Groq (Llama) — Extremely fast inference. Ideal for high-volume, straightforward tasks where low latency is the priority.

Writing Effective Instructions

The quality of your agent depends heavily on the instructions you write. Here are guidelines for getting the best results:

Be Specific About the Role

Start by clearly defining who the agent is and what it does. Instead of "Help with support," write something like: "You are a Tier 1 support agent for Acme Corp. Your job is to handle incoming Zendesk tickets, look up customer orders, and provide helpful responses."

Define the Persona

Set the tone and style. Should the agent be formal or casual? Brief or detailed? For example: "Respond in a friendly, professional tone. Keep replies concise — no more than 2-3 paragraphs unless the customer's question requires a detailed explanation."

Set Boundaries

Tell the agent what it should not do. This is just as important as telling it what to do. For example: "Never promise refunds without checking with the billing team. Do not share internal notes with customers. If you are unsure about a policy, say so rather than guessing."

Describe the Workflow

If the agent should follow a specific process, spell it out step by step. For example: "When a new ticket arrives: 1) Read the ticket and any previous conversation. 2) Look up the customer's order history. 3) Draft a reply addressing their issue. 4) If the issue requires escalation, tag the ticket as 'needs-escalation' and add an internal note."

Reference Available Tools

If the agent has access to specific tools, mention them in the instructions so the AI knows when and how to use them. For example: "Use the search_tickets tool to find related tickets before responding. Use add_public_reply to send the response directly."

Assigning Connectors and Tools

Connectors give your agent the ability to interact with external services. When you assign a connector to an agent, you then choose which specific tools from that connector the agent can use.

For example, if you assign a Zendesk connector, you might enable tools like get_ticket, search_tickets, and add_public_reply — but leave out update_priority if you do not want the agent changing ticket priority.

Some tools are marked as requiring confirmation. These are typically write operations (like sending a reply or creating a refund) where you want a human to approve the action before it executes. When an agent tries to use a confirmation-required tool, the chat pauses and asks you to approve or reject.

Assigning Data Sources

Data sources give your agent access to knowledge — uploaded documents, website content, or live data from connected services like Google Docs and Notion. See the Data Sources documentation for full details on how this works.

When you add a data source to an agent, you can choose whether the agent has access to all documents in that source or only specific ones you select.

Prompt Suggestions

Each agent can have a set of prompt suggestions — starter messages that appear when a user opens a new chat with that agent. These help users understand what the agent can do and give them a quick way to get started.

Prompt suggestions are auto-generated based on the agent's instructions and capabilities. They are designed to showcase the agent's most useful features. You can regenerate them at any time if you update the agent's configuration.

Credit System

Every time an agent produces a response, it consumes credits. The number of credits varies by model — more capable models cost more per response. Credits are deducted once per complete assistant response, not per message or per tool call.

Key details about credits:

• Credit costs are defined per model and shown in the model selection dropdown.
• Your organization has a credit balance that all agents share.
• You will receive email alerts when your credits reach 50%, 80%, and 90% usage.
• Enterprise plans bypass credit limits entirely.

You can monitor your credit usage on the Billing page.