Creating Your First Agent

Agents are the core workers in Pencel. Each agent has a defined role, personality, and set of capabilities that determine how it approaches tasks. This guide walks you through creating your first agent from scratch.

What is an agent?

An agent is an AI-powered team member that you configure for a specific job. You give it a name, describe its role, set boundaries on what it can do, and assign it skills. Once created, you can assign it to workflows, chat with it directly, or let it respond to events in your workspace.

Step-by-step: Create an agent

1. Open the Agents view

Navigate to Agents in the left sidebar. You see a list of any existing agents, plus a New Agent button in the top-right corner.

2. Click New Agent

Click the button to open a blank agent editor. Pencel gives you a form with several fields to fill in.

3. Fill in the basics

• Name — A short, recognizable label. Pick something that describes the job, not the technology. Examples: "Operations Analyst," "Customer Onboarding Rep," "Weekly Report Writer."
• Role — A one-line summary of what this agent does. Think of it like a job title plus a brief mandate. For example: "Analyze operational data and surface insights for the leadership team."
• Description — A longer explanation of the agent's responsibilities, context it should know, and any constraints. Two to four sentences is plenty.

TIP

Write the role and description as if you are briefing a new hire. The more specific you are about what the agent should and should not do, the better it performs.

4. Set the risk tolerance

Risk tolerance controls how cautious the agent is when making decisions:

Level	What it means
Low	The agent asks for approval before taking any action that changes data or sends external messages. Best for sensitive workflows like finance or customer communications.
Medium	The agent handles routine actions on its own but pauses for anything unusual or high-impact. Good general-purpose setting.
High	The agent acts autonomously for most tasks, only pausing for truly critical decisions. Use this for well-tested, low-risk workflows.

Start with Medium if you are unsure. You can always adjust later.

5. Choose a preferred model

Pencel supports multiple AI models. Each model has different strengths:

• Claude models are strong at nuanced writing, analysis, and following complex instructions.
• GPT models offer broad general capability.
• Gemini models work well for tasks involving structured data.

Pick the one that best fits the agent's job. You can change this at any time without losing any of the agent's configuration or memory.

6. Configure plan approval

This setting determines what happens when the agent creates an action plan during a workflow run:

• Auto — The agent executes its plan immediately. Use this for trusted, well-tested workflows.
• Require Approval — The agent pauses and shows you the plan before executing. You review each step and approve or reject it.

WARNING

For your first agent, set this to Require Approval. This lets you observe how the agent thinks and catch any issues before they affect your operations.

7. Enable skills

Skills control which categories of external tools your agent can access in action mode. Toggle on the ones relevant to its job:

• Browser — Web fetching and browser automation (e.g., Playwright, Web Fetch).
• Search — Web and document search (e.g., Brave Search).
• Code — Source control and filesystem access (e.g., GitHub, Filesystem).
• Data — Database access (e.g., PostgreSQL, SQLite, Redis).
• Memory — Persistent knowledge graph for long-term recall.
• Custom — Imported and custom MCP servers.

Only enable what the agent actually needs. Disabling skills reduces token usage and keeps the agent focused.

8. Set status and save

Set the status to Active if you want the agent available immediately, or leave it Inactive while you finish configuring other parts of your workspace. Click Save.

Example: Operations Analyst agent

Here is a concrete example to follow:

• Name: Operations Analyst
• Role: Analyze weekly operations data and produce concise summaries with actionable recommendations.
• Description: You review sales pipeline data, customer support metrics, and team productivity reports. You focus on identifying trends, flagging anomalies, and recommending specific next steps. Keep summaries under 500 words. Always cite the data source for each finding.
• Risk tolerance: Medium
• Preferred model: Claude
• Plan approval: Require Approval
• Skills: Search, Data
• Status: Active

INFO

After saving, your agent appears in the Agents list. You can immediately start chatting with it in the chat panel, or assign it to a workflow.

Tips for effective agents

• One job per agent. An agent that does one thing well is more reliable than one that juggles five responsibilities.
• Be specific in the description. Mention formats, word limits, tone preferences, and what topics are out of scope.
• Pair with guidelines. After creating your agent, add workspace or workflow-level guidelines to further shape its behavior. See the guidelines guide for details.
• Test in chat first. Before assigning your agent to an automated workflow, have a conversation with it to see how it responds.

Next steps

• Building a Workflow — Assign your agent to a multi-step workflow.
• Writing Guidelines — Add rules that shape how your agent behaves.
• Using Chat — Have a conversation with your new agent to test its responses.