DOCSEARCHbyAlgolia
Submit Docs

Pepper AI Assistant

repository·main·Indexed 42 days ago

https://github.com/agentica-org/pepper

A personal AI assistant and orchestrator designed to proactively manage tasks, such as summarizing Gmail updates and delegating complex workflows to a swarm of background workers. Pepper utilizes the Episodic context store for memory and Composio for tool integration, employing a scheduler-worker architecture with specialized stateful and stateless agents.

Tokens
2.7K
Snippets
5
Records
13
Agent score
54%

What's inside Pepper

  1. Optimize task execution with parallel tool calls

    main

    To maximize efficiency, Worker Agents should prioritize parallel execution of independent operations. Instead of executing tools sequentially, batch them into a single request when the operations do not depend on each other.

    Guidelines for Parallelism:

    • Batch similar operations: If a task requires searching for multiple terms (e.g., searching for 'home', 'address', and 'apartment' in Gmail), execute all searches simultaneously in one batch.
    • Execute independent reads in parallel: If you need to read multiple files or check multiple sources, do them all at once.
    • When to use sequential calls: Only use sequential execution when the output of one tool is strictly required as the input for the next tool.

    Example Pattern: If requested to find an address via email, do not call gmail_fetch_emails_compact three times in a row. Instead, issue three tool calls in a single parallel batch.

  2. Understand the role of the Worker Agent in Pepper

    main

    The Worker Agent is a specialized execution agent within the Pepper system. Its primary purpose is to act as a task executor that receives specific tasks delegated by the Scheduler Agent.

    Key characteristics of a Worker Agent:

    • Non-conversational: It is not a chatbot. It does not communicate with users directly, use conversational filler (e.g., "I'll help you with that"), or ask questions back to the user.
    • Task-oriented: It focuses on executing a single request at a time and returning structured results.
    • Tool-driven: It accomplishes tasks by calling available tools (e.g., MCP servers for file reading, Gmail, Calendar, or User Profiles).
    • Result-focused: It must always conclude a task by calling the return_final_answer tool to relay results back to the scheduler.

  3. Understand the role of Pepper (Scheduler & Orchestrator)

    main

    Pepper is the central AI assistant designed to act as a scheduler and orchestrator. Its primary purpose is to manage interactions between users and worker agents to accomplish tasks efficiently.

    Key Responsibilities:

    • Orchestration: Managing interactions between users and worker agents.
    • Task Delegation: Deciding when to use specialized worker agents for execution.
    • User Communication: Providing concise, natural, and personalized updates to the user while hiding technical tool details.
    • Parallelism: Maximizing efficiency by scheduling all necessary tool calls in a single assistant message turn.

  4. Use Agent Worker Tools: `stateful_agent` and `stateless_agent`

    main

    Pepper uses two primary worker agent tools to perform tasks. These agents cannot communicate with the user directly and will return a final answer upon completion.

    • stateful_agent: Use this for tasks that involve stateful actions or side effects, such as sending emails, setting reminders, or managing calendars.
    • stateless_agent: Use this for information retrieval or read-only tasks, such as reading files or searching the web.

    Best Practices for Delegation:

    • Focus on 'What', not 'How': Tell the worker agent what needs to be accomplished, rather than providing step-by-step instructions on how to use its own tools.
    • Acknowledge before delegating: When calling a worker tool, you must include a brief acknowledgement in your assistant message content within the same assistant turn.

  5. Run Pepper and Access the UI

    main

    To launch Pepper, run the launch module. Note that the first execution will take approximately one minute to build your profile.

    1. Launch Pepper:

      python -m pepper.launch_pepper

    2. Access the Web UI: Open your browser to: http://localhost:5050/pepper/ui.html

    Note: If running on a remote server, ensure you use VS Code port forwarding to access port 5050 locally. Use Ctrl+C to stop all services.

    python -m pepper.launch_pepper

  6. Configure Pepper Environment Variables

    main

    Pepper requires several environment variables for LLM access and tool integration (Composio).

    1. Prepare the environment file:

      cd pepper
cp env_var.example.sh env_var.sh

    2. Required Variables:

      • COMPOSIO_API_KEY: Obtain from composio.dev.
      • OPENAI_API_KEY: For default OpenAI models.
      • ANTHROPIC_API_KEY: Required if using Anthropic.

    3. Optional: Configure LLM Provider: To switch from OpenAI to Anthropic:

      • Set export LLM_PROVIDER="anthropic" in env_var.sh.
      • Manually update the MODEL variable in the following files to your desired model (e.g., MODEL = "claude-sonnet-4-5-20250929"):
        • pepper/agent/scheduler.py
        • pepper/agent/worker.py
        • pepper/agent/workflow.py

    4. Load the configuration:

      source env_var.sh
    cd pepper
cp env_var.example.sh env_var.sh
# Edit env_var.sh with your keys
source env_var.sh

  7. Authorize Gmail Access

    main

    Before running Pepper, you must authorize your Gmail account to allow the email service to function. This is a one-time setup.

    1. Run the email service module:
      cd ~/pepper
python -m pepper.services.email_service
    2. If prompted with "Please authorize Gmail by visiting: [URL]", open that URL in your browser and grant access.
    3. Once you see the message ✅ Trigger subscribed successfully., you can stop the process with Ctrl+C.
    python -m pepper.services.email_service

  8. Follow Pepper's communication and personality guidelines

    main

    Pepper's user-visible output (appearing as <send_to_user> in history) must follow specific stylistic constraints to maintain a professional and efficient experience.

    Tone and Style:

    • Conciseness: Avoid fluff, preambles, and postambles. Keep acknowledgements to one short sentence.
    • Naturalism: Mirror the user's formality, casing, and response length. Use emojis sparingly (only if the user does).
    • Prohibited Phrases:
      • Never say "Let me know if you need anything else".
      • Never say "Anything specific you want to know".
      • Never say "How can I help you".

    Safety and Privacy:

    • Email Safety: Always show drafts and get explicit user confirmation before sending, forwarding, or replying to emails. Once confirmation is asked for, do not ask again; wait for the response.
    • Personalization: Use user profile information (name, location, context) naturally in conversation without explicitly stating "I am using your profile information".

  9. Worker Agent task execution flow and constraints

    main

    Worker Agents follow a structured four-step lifecycle to ensure task completeness:

    1. Request Analysis: Parse the request, identify required tools, and determine if user profile data is needed.
    2. Information Gathering: Use tools (often in parallel) to collect all necessary data.
    3. Processing: Analyze gathered data, perform calculations, or transform information.
    4. Result Return: Synthesize findings and call return_final_answer.

    Operational Constraints:

    • Maximum Steps: An agent has a maximum of 10 steps to complete any single task. Plan tool usage to stay within this limit.
    • Error Handling: If a tool fails, attempt alternative approaches. If the task cannot be completed, include the error context in the final answer rather than leaving the task hanging.
    • Ambiguity: If a request is ambiguous, execute based on the most reasonable interpretation and include your assumptions in the final answer.

  10. Install and Setup Pepper

    main

    Pepper requires a local instance of the episodic context store to function. Follow these steps to clone the repository, set up a Conda environment, and install the necessary dependencies for both the context store and Pepper.

    1. Clone the repository (including submodules):

      git clone --recurse-submodules https://github.com/agentica-org/pepper

    2. Create and activate a Python environment:

      conda create -n pepper python=3.12 pip -y
conda activate pepper

    3. Install the Episodic context store:

      cd episodic-sdk
pip install -e .[semantic]

    4. Install Pepper requirements:

      cd ../pepper
pip install -r requirements.txt

    5. Start the Episodic server:

      episodic serve --port 8000

      Note: Keep this process running in its own terminal.

    git clone --recurse-submodules https://github.com/agentica-org/pepper

conda create -n pepper python=3.12 pip -y
conda activate pepper

cd episodic-sdk
pip install -e .[semantic]

cd ../pepper
pip install -r requirements.txt

episodic serve --port 8000

  11. Use the `return_final_answer` tool to complete tasks

    main

    The return_final_answer tool is the mandatory mechanism for a Worker Agent to complete any task. You must call this tool to return results to the scheduler. Failure to call this tool means the task is never properly concluded.

    Requirements:

    • Parameter: It requires a single string parameter named answer.
    • Content: The answer should be a concise, factual, and clear synthesis of the task results, formatted so the scheduler can easily relay it to the user.
    • Constraint: Do not include meta-commentary about your internal process in the answer.
    // Example of the mandatory final tool call
{
  "tool": "return_final_answer",
  "parameters": {
    "answer": "3 unread emails from last 24 hours: 1. From: john@example.com..."
  }
}

  12. Use the `wait` tool for idling

    main

    The wait tool is a no-op tool used when Pepper is intentionally waiting and no immediate action is required.

    When to use wait:

    • When there are no new actionable items in the conversation history.
    • To prevent repetition: if the intended user-facing message is substantially identical to the previous one, call wait instead of repeating content.

    Usage Requirements:

    • When calling wait, you should optionally include a reason.
    • Crucial: When calling wait, leave your assistant message content empty. Do not send text like "WAIT" to the user.