GitHub Copilot X: Agent Mode Tutorial

GitHub Copilot X has taken the developer experience to a whole new level by introducing Agent Mode, a paradigm where AI‑driven agents can act autonomously, collaborate with you, and even execute code on your behalf. In this tutorial we’ll walk through the fundamentals of Agent Mode, set up your environment, and build a couple of working agents that solve real‑world problems. By the end you’ll not only understand how to harness Copilot X as a powerful assistant, but also how to extend it with custom logic that fits your workflow.

What is Agent Mode?

Agent Mode is the evolution of Copilot’s inline suggestions into a full‑featured conversational partner that can run tasks, fetch data, and iterate on code without you typing every line. Think of it as a “co‑pilot” that can take a high‑level instruction—like “generate a CRUD API for a Todo app”—and orchestrate the steps needed to deliver a complete solution.

Under the hood, Agent Mode combines three pillars: a large language model (LLM) for understanding intent, a sandboxed execution environment for safe code runs, and a set of extensible plugins that let you expose domain‑specific tools. This architecture gives you the flexibility to use the built‑in agents (Chat, Terminal, and Documentation) or roll out your own custom agents tailored to internal APIs or proprietary data.

Setting Up Copilot X for Agent Mode

Before you can start building agents, make sure you have the latest version of Visual Studio Code (VS Code) and the GitHub Copilot extension installed. Agent Mode is gated behind a preview flag, so you’ll need to enable it in your user settings.

# Open VS Code settings (JSON)
{
    "github.copilot.enable": true,
    "github.copilot.experimental.agentMode": true,
    "github.copilot.experimental.enableChat": true
}

After saving the settings, restart VS Code. You’ll notice a new “Copilot Chat” pane on the right side of the editor—this is the entry point for interacting with agents. Sign in with your GitHub account, and you’ll be prompted to accept the Agent Mode terms of service, which outlines the sandbox execution policies.

Now that the environment is ready, let’s explore the first built‑in agent: the Copilot Chat.

Getting Started with the Copilot Chat Agent

The Copilot Chat agent works like a conversational IDE assistant. You can ask it to write functions, refactor code, or even run shell commands—all from the chat window. Try a simple request to generate a Python function that validates an email address.

def is_valid_email(email: str) -> bool:
    import re
    pattern = r'^[\w\.-]+@[\w\.-]+\.\w+$'
    return bool(re.match(pattern, email))

Notice how the chat not only provides the implementation but also explains the regular expression used. If you need a quick test, ask the agent to run the function with a few sample inputs; the sandbox will execute the code and return the results safely.

Running Commands in the Sandbox

Agent Mode’s sandbox can execute shell commands, which is handy for tasks like installing dependencies or checking repository status. For example, you can ask the chat to list the current Git branches:

git branch -a

The agent will return the output as plain text, and you can follow up with “checkout the feature branch named `feature/agent-demo`”. The chat will generate the appropriate `git checkout` command and execute it for you, all while keeping your workspace clean.

Building a Custom Agent with the Copilot SDK

While the built‑in agents cover many everyday scenarios, you might want an agent that knows your internal APIs or business rules. GitHub provides a lightweight SDK that lets you define custom agents in Python. The SDK runs in a separate process, communicates over JSON‑RPC, and respects the same sandbox constraints.

First, install the SDK package:

pip install copilot-agent-sdk

Next, create a new file called weather_agent.py. This agent will fetch current weather data from a public API and summarize it for the user.

import json
import requests
from copilot_agent_sdk import Agent, register

class WeatherAgent(Agent):
    def handle(self, request: dict) -> dict:
        city = request.get("city", "San Francisco")
        api_key = "YOUR_OPENWEATHER_API_KEY"
        url = f"https://api.openweathermap.org/data/2.5/weather?q={city}&appid={api_key}&units=metric"
        resp = requests.get(url)
        data = resp.json()

        if resp.status_code != 200:
            return {"error": data.get("message", "Failed to fetch weather")}

        weather = data["weather"][0]["description"]
        temp = data["main"]["temp"]
        summary = f"The weather in {city} is {weather} with a temperature of {temp}°C."
        return {"summary": summary}

# Register the agent so Copilot can discover it
register(WeatherAgent(), name="weather")

Run the agent locally with the SDK’s development server:

copilot-agent run weather_agent.py

Now switch back to the Copilot Chat pane, type /agent weather city=Berlin, and watch the agent return a concise weather summary. The interaction feels seamless, as if you were chatting with a built‑in feature.

Exposing Internal Services

Custom agents can also act as a bridge to private services. Suppose your company has an internal ticketing system with a REST endpoint /api/tickets. You can create an agent that creates tickets on your behalf, using the same SDK pattern but with authentication handled via environment variables.

class TicketAgent(Agent):
    def handle(self, request: dict) -> dict:
        title = request.get("title")
        description = request.get("description", "")
        token = os.getenv("TICKETING_API_TOKEN")
        headers = {"Authorization": f"Bearer {token}"}
        payload = {"title": title, "description": description}
        resp = requests.post("https://internal.company.com/api/tickets", json=payload, headers=headers)
        if resp.status_code == 201:
            ticket_id = resp.json()["id"]
            return {"ticket_id": ticket_id, "message": f"Ticket #{ticket_id} created successfully."}
        else:
            return {"error": resp.text}

After registering this agent, you can simply ask Copilot: /agent ticket title="Bug in login flow" description="Users see a 500 error when submitting the form". The agent will create the ticket and respond with the ID, removing the need to switch contexts.

Real‑World Use Cases for Agent Mode

1. Rapid Prototyping – Developers can describe a feature in plain English, and an agent will scaffold the entire module, complete with tests and documentation. This accelerates the feedback loop during sprint planning.

2. DevOps Automation – Agents can manage CI/CD pipelines, spin up containers, or roll back releases based on conversational commands. By integrating with tools like GitHub Actions, you can trigger workflows directly from the chat.

3. Knowledge Base Retrieval – When paired with a vector store of internal docs, an agent can answer policy questions, locate code snippets, or suggest best‑practice patterns, reducing time spent searching Confluence or legacy wikis.

4. Customer Support Tools – Support engineers can use a custom agent to pull user data, check subscription status, and generate response drafts, all without leaving the ticketing interface.

Performance and Security Considerations

Agent Mode executes code in an isolated sandbox that enforces resource limits (CPU, memory, and execution time). While this protects your machine, it also means long‑running jobs must be broken into smaller steps or delegated to external services.

Security is a top priority. The sandbox strips network access by default, except for domains you explicitly whitelist in the agent.config.json file. Always store secrets (API keys, tokens) in environment variables, never hard‑code them in the agent source.

• Whitelist Example:

{
    "network": {
        "allowed_domains": ["api.openweathermap.org", "internal.company.com"]
    }
}

Additionally, enable the “audit log” feature to keep a record of every command an agent runs. This log can be streamed to a SIEM solution for compliance monitoring.

Pro Tips for Mastering Agent Mode

Tip 1 – Prompt Engineering: Start with a clear, high‑level intent, then iteratively refine. For example, ask “Create a Flask endpoint that returns weather data” before adding “Use the WeatherAgent we built earlier”. This guides the LLM to reuse existing agents instead of reinventing them.

Tip 2 – Reuse Agent Names: Give each custom agent a concise, descriptive name (e.g., weather, ticket). The shorter the name, the easier it is to invoke via /agent commands, especially when working under pressure.

Tip 3 – Debug with --verbose: Run the SDK with the --verbose flag to see the raw JSON request/response cycle. This is invaluable when your agent isn’t behaving as expected.

Advanced Example: End‑to‑End Feature Generation

Let’s combine everything we’ve learned into a single workflow that generates a full‑stack feature: a “Quote of the Day” widget that fetches a random quote from an external API, stores it in a SQLite database, and serves it via a FastAPI endpoint. We’ll use three agents: weather (as a template for external calls), db (custom agent for DB operations), and api (custom agent for FastAPI scaffolding).

Step 1 – Create the Database Agent

class DBAgent(Agent):
    def __init__(self):
        self.conn = sqlite3.connect(":memory:")
        self.conn.execute("""CREATE TABLE IF NOT EXISTS quotes (
                                id INTEGER PRIMARY KEY AUTOINCREMENT,
                                text TEXT NOT NULL,
                                author TEXT
                            )""")
        self.conn.commit()

    def handle(self, request: dict) -> dict:
        action = request.get("action")
        if action == "insert":
            text = request["text"]
            author = request.get("author", "Unknown")
            self.conn.execute("INSERT INTO quotes (text, author) VALUES (?, ?)", (text, author))
            self.conn.commit()
            return {"status": "inserted"}
        elif action == "random":
            cur = self.conn.execute("SELECT text, author FROM quotes ORDER BY RANDOM() LIMIT 1")
            row = cur.fetchone()
            return {"quote": row[0], "author": row[1]} if row else {"error": "No quotes stored"}
        else:
            return {"error": f"Unsupported action {action}"}

Register it as db and start the agent server.

Step 2 – Generate the Quote Fetcher

Ask Copilot to write a small script that pulls a random quote from https://api.quotable.io/random and stores it using the db agent.

import requests
import json
import subprocess

def fetch_and_store():
    resp = requests.get("https://api.quotable.io/random")
    data = resp.json()
    quote = data["content"]
    author = data["author"]
    # Send to DB agent
    payload = {"action": "insert", "text": quote, "author": author}
    # Assume we have a CLI to talk to the DB agent
    subprocess.run(["copilot-agent", "call", "db", json.dumps(payload)], check=True)

if __name__ == "__main__":
    fetch_and_store()

Run this script once a day using a cron job or GitHub Action, and the database will stay populated.

Step 3 – Scaffold the FastAPI Endpoint

Now ask Copilot to generate a FastAPI app that queries the db agent for a random quote and returns JSON.

from fastapi import FastAPI
import subprocess
import json

app = FastAPI()

@app.get("/quote")
def get_quote():
    # Query the DB agent for a random quote
    result = subprocess.check_output(
        ["copilot-agent", "call", "db", json.dumps({"action": "random"})]
    )
    data = json.loads(result)
    if "error" in data:
        return {"error": data["error"]}
    return {"quote": data["quote"], "author": data["author"]}

Deploy the FastAPI app with a simple Dockerfile, and you now have a fully functional “Quote of the Day” service built entirely through conversational commands and custom agents.

Best Practices for Maintaining Agents

• Version Control: Keep each agent in its own repository or subdirectory, and tag releases. This makes it easy to roll back if a regression appears.
• Testing: Write unit tests for the handle method using the SDK’s mock client. Automated tests ensure that changes to external APIs don’t break your agents.
• Documentation: Use docstrings and a README.md that explains the expected JSON schema for requests. Copilot can then generate accurate usage hints.
• Observability: Emit structured logs (JSON) from each agent. Combine them with the audit log for end‑to‑end traceability.

Conclusion

Agent Mode transforms GitHub Copilot from a code‑completion tool into an interactive development partner capable of running code, accessing services, and automating repetitive tasks. By enabling the preview flag, leveraging the Copilot SDK, and following the best practices outlined above, you can build custom agents that streamline workflows, enforce internal policies, and accelerate feature delivery. Whether you’re prototyping a new API, automating DevOps chores, or integrating proprietary systems, Agent Mode equips you with a conversational interface that bridges intent and execution—making every line of code feel a little more magical.