From e1e582e0ddbfa3e3e94197e1b9c681a187f7337f Mon Sep 17 00:00:00 2001 From: Sathvik Bhagavan Date: Tue, 13 Jan 2026 16:34:16 +0100 Subject: [PATCH] docs: add Code Review Assistant Tutorial using AgentSpec in notebooks --- README.md | 11 +- notebooks/README.md | 11 +- .../code_review_assistant_agentspec.ipynb | 454 ++++++++++++++++++ 3 files changed, 466 insertions(+), 10 deletions(-) create mode 100644 notebooks/agentspec/code_review_assistant_agentspec.ipynb diff --git a/README.md b/README.md index c87240ff6..b63fee107 100644 --- a/README.md +++ b/README.md @@ -24,11 +24,12 @@ Jupyter notebooks and interactive tutorials covering: - Data preparation and analysis workflows - Agent development and orchestration examples -| Name | Description | Stack | Link | -| --------------------------------- | ---------------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| memory_context_engineering_agents | Build AI agents with 6 types of persistent memory. | LangChain, Oracle AI Database, OpenAI, Tavily | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./notebooks/memory_context_engineering_agents.ipynb) | -| oracle_rag_agents_zero_to_hero | Learn to build RAG agents from scratch using Oracle AI Database. | Oracle AI Database, OpenAI, OpenAI Agents SDK | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./notebooks/oracle_rag_agents_zero_to_hero.ipynb) | -| oracle_rag_with_evals | Build RAG systems with comprehensive evaluation metrics | Oracle AI Database, OpenAI, BEIR, Galileo | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./notebooks/oracle_rag_with_evals.ipynb) | +| Name | Description | Stack | Link | +| --------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| memory_context_engineering_agents | Build AI agents with 6 types of persistent memory. | LangChain, Oracle AI Database, OpenAI, Tavily | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./notebooks/memory_context_engineering_agents.ipynb) | +| oracle_rag_agents_zero_to_hero | Learn to build RAG agents from scratch using Oracle AI Database. | Oracle AI Database, OpenAI, OpenAI Agents SDK | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./notebooks/oracle_rag_agents_zero_to_hero.ipynb) | +| oracle_rag_with_evals | Build RAG systems with comprehensive evaluation metrics | Oracle AI Database, OpenAI, BEIR, Galileo | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./notebooks/oracle_rag_with_evals.ipynb) | +| code_review_assistant_agentspec | Build an AI agent specialized in code review assistance using AgentSpec | Agent Spec, Wayflow, Langgraph | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./notebooks/agentspec/code_review_assistant_agentspec.ipynb) | ### 🎓 **Workshops** (`/workshops`) diff --git a/notebooks/README.md b/notebooks/README.md index a4cdc23de..bd26d038a 100644 --- a/notebooks/README.md +++ b/notebooks/README.md @@ -15,11 +15,12 @@ The notebooks cover various aspects of AI development including: ## Notebooks -| Title | Stack | Use Case | Notebook | -| ------------------------------------------ | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| Memory & Context Engineering for AI Agents | LangChain, Oracle AI Database, OpenAI, Tavily | Build AI agents with 6 types of persistent memory. Covers memory engineering, context window management, and just-in-time retrieval patterns. | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./memory_context_engineering_agents.ipynb) | -| Oracle RAG Agents: Zero to Hero | Oracle AI Database, OpenAI, OpenAI Agents SDK | Learn to build RAG agents from scratch using Oracle AI Database. | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./oracle_rag_agents_zero_to_hero.ipynb) | -| Oracle RAG with Evaluations | Oracle AI Database, OpenAI, BEIR, Galileo | Build RAG systems with comprehensive evaluation metrics. | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./oracle_rag_with_evals.ipynb) | +| Title | Stack | Use Case | Notebook | +| ------------------------------------------ | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| Memory & Context Engineering for AI Agents | LangChain, Oracle AI Database, OpenAI, Tavily | Build AI agents with 6 types of persistent memory. Covers memory engineering, context window management, and just-in-time retrieval patterns. | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./memory_context_engineering_agents.ipynb) | +| Oracle RAG Agents: Zero to Hero | Oracle AI Database, OpenAI, OpenAI Agents SDK | Learn to build RAG agents from scratch using Oracle AI Database. | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./oracle_rag_agents_zero_to_hero.ipynb) | +| Oracle RAG with Evaluations | Oracle AI Database, OpenAI, BEIR, Galileo | Build RAG systems with comprehensive evaluation metrics. | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./oracle_rag_with_evals.ipynb) | +| Code Review Assistant AgentSpec | Agent Spec, Wayflow, Langgraph | Build an AI agent specialized in code review assistance using AgentSpec. | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](./agentspec/code_review_assistant_agentspec.ipynb) | ## Getting Started diff --git a/notebooks/agentspec/code_review_assistant_agentspec.ipynb b/notebooks/agentspec/code_review_assistant_agentspec.ipynb new file mode 100644 index 000000000..8303257fc --- /dev/null +++ b/notebooks/agentspec/code_review_assistant_agentspec.ipynb @@ -0,0 +1,454 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "a10294ea", + "metadata": {}, + "source": [ + "# Tutorial: Building a Code Review Assistant with MCP in Agent Spec\n", + "\n", + "*In this tutorial, we will create a powerful code review assistant using Agent Spec and MCP to automate pull request reviews, enhancing code quality with AI-driven insights.*\n", + "\n", + "![image](https://miro.medium.com/v2/resize:fit:600/format:webp/1*_LJLsR-EL1Ua_vXIAuBLxg.png)" + ] + }, + { + "cell_type": "markdown", + "id": "36c3f0c8", + "metadata": {}, + "source": [ + "## Introduction\n", + "\n", + "In today’s fast-paced development environment, code reviews are crucial but can be time-consuming. This tutorial is designed for individuals and teams who want to leverage the power of AI agents to automate the review of pull requests. Whether you’re working on open-source projects or enterprise software, integrating AI-powered code review tools can save time, reduce errors, and ensure coding standards are consistently enforced.\n", + "\n", + "The goal of this guide is to walk you through the process of building a **Code Review Assistant** using Agent Spec, a framework-agnostic specification for portable AI agents and MCP (Model Context Protocol), which enables seamless interaction with tools and external systems. By the end of this tutorial, you’ll have a functional assistant capable of analyzing code changes and providing detailed feedback with actionable insights.\n", + "\n", + "You’ll also discover how to export and reuse your assistant across multiple compatible agentic frameworks, giving you ultimate flexibility.\n", + "\n", + "## Why Agent Spec?\n", + "\n", + "**Agent Spec** is a framework-agnostic declarative specification designed to make AI agents and workflows portable, reusable, and executable across any compatible framework.\n", + "\n", + "**Agent Spec** addresses the ongoing challenge of fragmentation in AI agent development, where different frameworks like AutoGen, LangGraph, and CrewAI lack a shared foundation, hindering portability and reuse.\n", + "\n", + "**Agent Spec** enables developers to define AI agents and workflows that can be easily run, maintained, and adapted across various platforms and runtimes without rewriting code. This standardization benefits enterprises by streamlining scalability, reducing platform lock-in, simplifying maintenance, and enabling seamless collaboration both internally and with external partners.\n", + "\n", + "You can find more about the Agent Spec motivation and vision at https://oracle.github.io/agent-spec/agentspec/intro_and_motivation.html\n", + "\n", + "Also, you can read the full Agent Spec documentation at https://oracle.github.io/agent-spec/\n", + "\n", + "We will use WayFlow (see https://github.com/oracle/wayflow) and LangGraph (see https://github.com/langchain-ai/langgraph) as the runtimes in this tutorial.\n", + "\n", + "## Tutorial Overview: What we are building\n", + "\n", + "![image2](https://miro.medium.com/v2/resize:fit:600/format:webp/1*nXUzkrS2bcp144EEwZPx_g.png)\n", + "\n", + "In this tutorial, we are building a Code Assistant specifically designed for reviewing GitHub pull requests. The assistant will be equipped with tools to interact with GitHub, analyze code changes, and provide detailed feedback to improve code quality.\n", + "\n", + "The agent leverages MCP (Model Context Protocol) tools to connect with GitHub, allowing it to list pull requests, read their contents, and retrieve file details for comprehensive reviews.\n", + "\n", + "![image4](https://miro.medium.com/v2/resize:fit:600/format:webp/1*P4n7o5dOCXU4TdJuTQ10Xg.png)\n", + "\n", + "[MCP](https://modelcontextprotocol.io/docs/getting-started/intro) is a standardized framework that streamlines communication between AI agents and external systems through a consistent and secure interface. It provides a suite of tools and protocols for agents to perform various tasks, access multiple data sources, and integrate with different platforms seamlessly. \n", + "\n", + "By simplifying the process of connecting with disparate systems, MCP allows developers to focus on building core agent functionality without getting bogged down by the details of each integration. This results in greater flexibility and scalability for AI-based solutions.\n", + "\n", + "Let’s get started!\n", + "\n", + "## Step 1. Setting up the environment\n", + "\n", + "First, let's create and activate a virtual environment (outside of this Notebook):\n", + "\n", + "```bash\n", + "# Create and activate a virtual environment (run in your terminal)\n", + "python -m venv venv-agentspec \n", + "source venv-agentspec/bin/activate # On Windows: venv-agentspec\\Scripts\\activate\n", + "```\n", + "\n", + "Next, let’s install pyagentspec, wayflowcore which are the packages we need to run this tutorial.\n", + "\n", + "```bash\n", + "pip install \"pyagentspec[langgraph_mcp]@git+https://github.com/oracle/agent-spec@main#subdirectory=pyagentspec\"\n", + "pip install \"wayflowcore@git+https://github.com/oracle/wayflow@main#subdirectory=wayflowcore\"\n", + "```\n", + "\n", + "You can also clone the repositories to stay up to date with the latest features ([agent-spec](https://github.com/oracle/agent-spec), [wayflow](https://github.com/oracle/wayflow)).\n", + "\n", + "## Step 2. Configuring your LLM\n", + "\n", + "WayFlow supports several LLM API providers. For an overview of supported LLMs, see the guide [How to Use LLMs from Different Providers](https://oracle.github.io/wayflow/core/howtoguides/llm_from_different_providers.html).\n", + "\n", + "Start by selecting an LLM from one of the available providers:\n", + "\n", + "You can use model providers such as OpenAI:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "4e0272c8", + "metadata": {}, + "outputs": [], + "source": [ + "from pyagentspec.llms import OpenAiConfig\n", + "\n", + "llm_config = OpenAiConfig(\n", + " name=\"openai-llm\",\n", + " model_id=\"model-id\", # e.g. \"gpt-4.1\"\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "909603c8", + "metadata": {}, + "source": [ + "And you can also use locally models, e.g. with Ollama:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e238e7ca", + "metadata": {}, + "outputs": [], + "source": [ + "from pyagentspec.llms import OllamaConfig\n", + "\n", + "llm_config = OllamaConfig(\n", + " name=\"ollama-llm\",\n", + " model_id=\"model-id\", # e.g. gpt-oss:20b\n", + " url=\"url/to/ollama_model\" # e.g. localhost:11434\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "b3a7c185", + "metadata": {}, + "source": [ + "## Step 3. Setting up MCP Tools for the Agent\n", + "\n", + "MCP allows agents to interact with external services through a standardized client transport. In this tutorial, we’ll set up tools to interact with GitHub for reviewing pull requests.\n", + "\n", + "Agent Spec supports integration with MCP servers to provide tools dynamically. We’ll configure an MCP client to connect to the GitHub’s MCP server:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d3266c72", + "metadata": {}, + "outputs": [], + "source": [ + "from pyagentspec.mcp.clienttransport import StreamableHTTPTransport \n", + "from pyagentspec.mcp.tools import MCPToolBox \n", + "\n", + "mcp_server_url = \"https://api.githubcopilot.com/mcp/\" \n", + "headers = {\"Authorization\": f\"Bearer {'GITHUB_PERSONAL_ACCESS_TOKEN'}\"}\n", + "mcp_client = StreamableHTTPTransport(\n", + " name=\"mcp_client\", url=mcp_server_url, headers=headers\n", + ")\n", + "mcp_toolbox = MCPToolBox(\n", + " name=\"mcp_toolbox\", \n", + " client_transport=mcp_client, \n", + " tool_filter=[\n", + " \"list_pull_requests\", \"pull_request_read\", \"get_file_contents\"\n", + " ]\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "5ccbd53a", + "metadata": {}, + "source": [ + "Here, the `MCPToolBox` is configured with specific tools like `list_pull_requests`, `pull_request_read` and `get_file_contents` to interact with GitHub pull requests and repository contents. To manage context length and avoid overwhelming the agent with excessive data, we use only the tools that are necessary for the task at hand. For example, we use `list_pull_requests` to see available PRs, `pull_request_read` to review a specific PR, and `get_file_contents` to access relevant files. This focused approach helps keep the context concise and relevant.\n", + "\n", + "To discover available tools and their names, refer to the MCP server documentation or the specific service integration guide you’re using (e.g., [GitHub MCP server documentation](https://github.com/github/github-mcp-server)). These resources will list the tools provided by the server, their purposes, and any required parameters, ensuring you select the most appropriate tools for your agent’s tasks.\n", + "\n", + "**Note:** To obtain a GitHub Personal Access Token, visit https://github.com/settings/tokens, click on “Generate new token”, select the necessary permissions (e.g., repo access for pull requests), and copy the generated token. Replace ‘GITHUB_PERSONAL_ACCESS_TOKEN’ with your actual token in the code above. Ensure you keep this token secure and do not commit it to version control.\n", + "\n", + "## Step 4. Writing the Instructions for the Agent\n", + "The instructions (also known as the system prompt) define the agent’s behavior. Here, the instructions describe the agent’s persona (Code Reviewer), the workflow to follow for reviewing pull requests, and the expected output format.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "99426941", + "metadata": {}, + "outputs": [], + "source": [ + "CUSTOM_INSTRUCTIONS = \"\"\" \n", + " You are an experienced code reviewer analyzing GitHub pull requests. Your primary goal is to understand proposed changes and deliver thorough, constructive feedback that enhances code quality and project alignment.\n", + "**Workflow:** \n", + " - **1. PR Overview:** Begin by gathering high-level details about the pull request. \n", + " - **2. Changed Files & Diffs:** Retrieve and review all modified files and code diffs. \n", + " - **3. Context Gathering:** Load any additional related files as needed (tests, configs). Review repository structure for context if necessary. \n", + " - **4. Code Analysis:** Examine the code for correctness, maintainability, standards compliance, performance, security, and architectural impact. \n", + " - **5. Inline Comments:** Provide specific, actionable comments on significant code changes, including suggestions for improvement where relevant. \n", + " - **6. Summary Assessment:** Conclude with a clear summary, using this structure: \n", + " i. **Description:** What the PR does. \n", + " ii. **Strengths:** What's done well. \n", + " iii. **Opportunities for Improvement:** Areas to address. \n", + " iv. **Additional Suggestions:** Any further feedback.\n", + "**Guidelines:** \n", + "- Use Markdown. Use bullet points for everything.\n", + "- Include code snippets when suggesting changes.\n", + "- Complete all steps before responding.\n", + "- Keep feedback concise, specific, and actionable.\n", + "- Use all available tools to support your analysis. Most common usage for reference:\n", + " - `list_pull_requests` when the user does not specify a PR link.\n", + " - `pull_request_read` when the user gives a PR URL.\n", + " - `get_file_contents` if you need to inspect related files beyond the diff.\n", + "Your review should help authors deliver higher-quality code and foster continuous improvement. \n", + " \"\"\".strip()" + ] + }, + { + "cell_type": "markdown", + "id": "3a696a8c", + "metadata": {}, + "source": [ + "**Tip:** Debugging LLM Prompts: Passing a confusing prompt to an Agent may lead to unexpected behavior. If you receive an unexpected answer from the agent, try to directly ask the agent, “What led you to answer? Is there anything confusing in the given set of instructions?”\n", + "\n", + "Very often, LLMs will point to what is potentially confusing.\n", + "\n", + "## Step 5. Assembling the Agent\n", + "Now that the tools and instructions are ready, we can create the agent:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2206620f", + "metadata": {}, + "outputs": [], + "source": [ + "from pyagentspec.agent import Agent\n", + "agent_config = Agent( \n", + " name=\"github_agent\", \n", + " llm_config=llm_config, \n", + " system_prompt=CUSTOM_INSTRUCTIONS, \n", + " toolboxes=[mcp_toolbox] \n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "7dbc37a1", + "metadata": {}, + "source": [ + "## Step 6. Exporting the Agent to Agent Spec\n", + "We can now export the Agent Spec configuration. This configuration is framework agnostic, which means that you can author the assistant once and then re-use it with any Agent Spec compatible framework.\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "095dbb41", + "metadata": {}, + "outputs": [], + "source": [ + "from pyagentspec.serialization import AgentSpecSerializer\n", + "serialized_agent = AgentSpecSerializer().to_json(agent_config)" + ] + }, + { + "cell_type": "markdown", + "id": "4f402035", + "metadata": {}, + "source": [ + "You can find the Agent Spec configuration at https://github.com/oracle/agent-spec.\n", + "\n", + "## Step 7. Running the Agent\n", + "\n", + "We will now run the agent we defined above using multiple runtimes like WayFlow and LangGraph. This demonstrates the power of Agent Spec’s framework-agnostic design, allowing your assistant to operate across different environments and take advantage of each runtime’s unique strengths and optimizations for broader compatibility and flexibility.\n", + "\n", + "### A. Using WayFlow\n", + "\n", + "Let’s run this agent using WayFlow:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f3ea090e", + "metadata": {}, + "outputs": [], + "source": [ + "from wayflowcore.agentspec import AgentSpecLoader as WayFlowLoader \n", + "from wayflowcore.agent import Agent as RuntimeAgent \n", + "from wayflowcore.mcp import enable_mcp_without_auth\n", + "\n", + "enable_mcp_without_auth() \n", + "agent: RuntimeAgent = WayFlowLoader().load_json(serialized_agent)" + ] + }, + { + "cell_type": "markdown", + "id": "eec99ab7", + "metadata": {}, + "source": [ + "Note: Although `enable_mcp_without_auth()` is used, authentication still occurs through the Personal Access Token (PAT) described above. Ensure your PAT is securely stored and has the appropriate read/write permissions.\n", + "\n", + "Now, we have instantiated theagent. We can run it as:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c67bb2ae", + "metadata": {}, + "outputs": [], + "source": [ + "conversation = agent.start_conversation() \n", + "pr_link = \"\" \n", + "user_query = f\"Review changes of {pr_link}\"\n", + "conversation.append_user_message(user_query) \n", + "status = await conversation.execute_async()" + ] + }, + { + "cell_type": "markdown", + "id": "5eda6c42", + "metadata": {}, + "source": [ + "**Note:** Replace with the actual URL of the PR.\n", + "\n", + "### B. Using LangGraph\n", + "\n", + "We can also run it using LangGraph:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "5fa302cd", + "metadata": {}, + "outputs": [], + "source": [ + "import asyncio\n", + "from pyagentspec.adapters.langgraph import AgentSpecLoader\n", + "\n", + "langgraph_assistant = AgentSpecLoader().load_json(serialized_agent)\n", + "config = {\"configurable\": {\"thread_id\": \"1\"}}\n", + "\n", + "pr_link = \"\"\n", + "user_query = f\"Review changes of {pr_link}\"\n", + "\n", + "result = await langgraph_assistant.ainvoke(\n", + " {\"messages\": [{\"role\": \"user\", \"content\": user_query}]},\n", + " config,\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "ea137433", + "metadata": {}, + "source": [ + "\n", + "**Note:** Replace with the actual URL of the PR.\n", + "\n", + "Here is what the result may look like for both:\n", + "\n", + "> I've reviewed the pull request at . Below is my detailed feedback:\n", + "> - **Description:** This PR introduces enhancements to pretty printing. \n", + "> - **Strengths:** The code is well-structured, with clear documentation and logical organization. \n", + "> - **Opportunities for Improvement:** \n", + "> - Consider adding unit tests for the new configuration options to ensure robustness. \n", + "> - In `print.py`, line 45, the error handling for invalid inputs could be more comprehensive. \n", + "> - **Additional Suggestions:** It might be beneficial to include a changelog entry for visibility.\n", + "\n", + "Let me know if you'd like me to dive deeper into any specific file or aspect of this PR.\n", + "\n", + "👏 Congratulations, you have now built your first code assistant agent with Agent Spec and ran it using WayFlow and LangGraph!\n", + "\n", + "By now, you should have:\n", + "\n", + "- A Python script that defines a GitHub code review agent using Agent Spec.\n", + "- An MCP client configured to talk to the GitHub MCP server with authentication.\n", + "- The same agent running on WayFlow, via `WayFlowLoader.load_json(serialized_agent)` and Langgraph using `AgentSpecLoader.load_json(serialized_agent)`.\n", + "- An AI reviewer that can read PRs and produce structured feedback.\n", + "\n", + "## Common Errors\n", + "\n", + "When executing the agent, you might encounter several common errors. To troubleshoot effectively, enable detailed debug logs by adding the following at the beginning of your script:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "fdbc6dfe", + "metadata": {}, + "outputs": [], + "source": [ + "import logging\n", + "logging.basicConfig(level=logging.DEBUG)" + ] + }, + { + "cell_type": "markdown", + "id": "ce3ce088", + "metadata": {}, + "source": [ + "This will provide comprehensive logs to help identify issues. Below are some common errors and their potential causes or solutions:\n", + "\n", + "1. **Incorrect MCP Server URL:** If the URL to the MCP server is wrong, you will see a log entry indicating “HTTP/1.1 404 Not Found” for the specified URL. Double-check the server URL in your StreamableHTTPTransport configuration and ensure it matches the documented endpoint.\n", + "\n", + "2. **Invalid Personal Access Token (PAT):** An error like “Client error ‘400 Bad Request’ for url ‘https://api.githubcopilot.com/mcp'” typically indicates an incorrect PAT or insufficient permissions. Verify that your GitHub PAT is correct and has the necessary scopes and permissions. Regenerate a new token if needed at https://github.com/settings/tokens.\n", + "\n", + "3. **Incorrect Tool Name in Toolbox:** If a tool name specified in the MCPToolBox is wrong, you will encounter a `NoSuchToolFoundOnMCPServerError` in WayFlow. Review the tool names in your `tool_filter` list against the MCP server documentation (e.g., GitHub MCP server docs) to ensure they match exactly (e.g., `list_pull_requests`, not `list_prs`).\n", + "\n", + "4. **LLM Configuration Issues:** If your LLM fails to initialize, you might see errors related to invalid model IDs, API keys, or connection issues. For instance, with Ollama, a “ConnectionRefused” error indicates the local server URL might be incorrect or the server is not running. Verify your llm_config settings and ensure the model provider’s service is accessible.\n", + "\n", + "If you encounter an error not listed here, consult the debug logs for detailed stack traces and search for relevant error codes in the Agent Spec, WayFlow, or LangGraph documentation. Community forums and GitHub issues for these projects can also provide additional troubleshooting insights.\n", + "\n", + "## Going Further\n", + "\n", + "Now that you’ve built a basic Code Review Assistant, there are several ways to enhance its capabilities. Here are some concise suggestions to take your agent further:\n", + "\n", + "1. **Enable Commenting on Pull Requests:** Extend your agent to post comments on GitHub by adding the `pull_request_review_write` tool to your `MCPToolBox`. Update instructions to include posting inline feedback, integrating reviews into the development workflow.\n", + "\n", + "2. **Summarize Code Changes:** Add a workflow step to summarize code diffs before detailed review to manage context length. Process diffs from `pull_request_read` to create concise summaries for the agent to reference.\n", + "\n", + "3. **Support Multiple Repositories:** Enable handling of pull requests across multiple repositories. Adjust instructions to switch contexts based on user queries, possibly using dynamic tool setups or additional MCP tools.\n", + "\n", + "4. **Add Custom Review Criteria:** Tailor reviews with project-specific criteria by updating the system prompt with guidelines for patterns, naming, or performance. This ensures feedback matches team and project standards.\n", + "\n", + "These enhancements can greatly improve your Code Review Assistant’s functionality. Experiment with these ideas to adapt the agent to your needs.\n", + "\n", + "## GitHub Repository\n", + "\n", + "You can access all the code used in this article on the [AgentSpec GitHub](https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/code_examples/ext_code_assistant_tutorial.py).\n", + "\n", + "## Conclusion\n", + "\n", + "In this guide, you learned how to build a simple yet powerful Code Assistant Agent for GitHub pull request reviews by equipping an Agent with MCP tools using Agent Spec and ran it with Wayflow and LangGraph." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.3" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}