copilot_cli_agent#

CopilotCLIAgent: uses the GitHub Copilot CLI to autonomously work on a task.

Classes

CopilotCLIAgent(task, job_id, task_id, config)

Agent that uses the GitHub Copilot CLI to autonomously work on a task.

CopilotCLIBuildAndTestHandler()

Build-and-test handler used by the Copilot CLI agent.
class kernelfoundry.algorithm.copilot_cli_agent.CopilotCLIBuildAndTestHandler[source]#

Build-and-test handler used by the Copilot CLI agent.

This handler keeps the shared evaluation logic from BuildAndTestHandler and adds Copilot-specific end-of-session logging.

session_end(session_log: str, session_id: str, token_usage: dict | None = None) → None[source]#
class kernelfoundry.algorithm.copilot_cli_agent.CopilotCLIAgent(task: Task, job_id: int, task_id: str, config: dict, container_image: Image | None = None, copilot_exe: str = 'copilot', env_overrides: dict[str, str] | None = None, handler: BuildAndTestHandler | None = None, initial_session_state: dict | None = None, branch: int = 0, parent_session_uuid: str | None = None, parent_program: Program | None = None, skills: list[Skill] | None = None, extra_mcp_servers: dict[str, dict] | None = None)[source]#

Agent that uses the GitHub Copilot CLI to autonomously work on a task.

The agent launches the Copilot CLI as a subprocess, provides it with a KernelFoundry MCP server in _internal mode (file-based communication), and collects the (Program, EvalResult) pairs produced by each build_and_test tool call.

The workspace is created in a temporary directory and cleaned up after run() returns.

Parameters:

  • task – The task to work on.

  • job_id – Job ID associated with this run.

  • task_id – Task ID associated with this run.

  • container_image – Optional resolved Image. When provided, the Copilot CLI (and the MCP server it spawns) run inside a container created from this image.

  • copilot_exe – Path or name of the Copilot CLI binary. Use the copilot-sim script for local testing without GPU hardware.

  • env_overrides – Environment variable overrides passed to the Copilot subprocess in addition to the current process environment.

  • handler – A BuildAndTestHandler instance whose call() method is invoked after every build_and_test tool call. If omitted, CopilotCLIBuildAndTestHandler is used so the session log is emitted at the end of each run() invocation.

  • initial_session_state – Base64-encoded COPILOT_HOME contents for restoring a prior session (populated automatically by fork()).

  • branch – Branch number for this agent instance.

  • parent_session_uuid – The session UUID of the parent agent instance, if any.

  • parent_program – The program to be used as the parent for this agent instance, if any.

  • skills – Optional list of Skill instances that will be made available to the Copilot CLI agent.

  • extra_mcp_servers – Optional additional MCP server definitions merged with the default kernelfoundry MCP server.

__init__(task: Task, job_id: int, task_id: str, config: dict, container_image: Image | None = None, copilot_exe: str = 'copilot', env_overrides: dict[str, str] | None = None, handler: BuildAndTestHandler | None = None, initial_session_state: dict | None = None, branch: int = 0, parent_session_uuid: str | None = None, parent_program: Program | None = None, skills: list[Skill] | None = None, extra_mcp_servers: dict[str, dict] | None = None)[source]#

Initialize the agent with a starting point task and job ID.

Parameters:

  • task (Task) – The task for the agent to work on.

  • job_id (int) – The job ID associated with this agent.

  • config (dict) – The main configuration dictionary for the job.

  • container_image (Image | None) – Optional image for running the agent in a containerized environment.

  • initial_session_state (dict | None) – Optional session state to restore from a previous run, as returned by session_state(). When provided, the agent continues from that state rather than starting a fresh session.

  • build_test_handler – A BuildAndTestHandler instance whose call() method is invoked after every build_and_test tool call. Defaults to a plain BuildAndTestHandler instance.

  • branch – An integer identifier for the branch used for logging.

  • parent_session_uuid – The session UUID of the parent agent, if any.

  • parent_program – The program used as the parent for the next evaluation, if any.

  • skills – Optional list of Skill instances to make available to the agent. Any filtering is expected to be done by the caller.

run(prompt: str, iteration: int, timeout: float = 3600.0) → list[tuple[Program, EvalResult]][source]#

Run the Copilot CLI agent on the task.

The Copilot subprocess runs in a background thread while this thread drives the MCP file-based communication directly.

Parameters:

  • prompt – The input prompt piped into the Copilot CLI via stdin.

  • timeout – Maximum number of seconds to wait for the agent to finish. Defaults to 3600 (one hour). A TimeoutError is raised if the deadline is exceeded.

Returns:

A list of (Program, EvalResult) tuples — one entry per build_and_test tool call made by the agent during the session.

fork(branch: int, parent_program: Program | None = None) → CopilotCLIAgent[source]#

Create a new agent instance that continues from the current session state.

Must not be called while this agent is running.

session_state() → dict[source]#

Return the serialized COPILOT_HOME as a JSON-serialisable dict.

The values are base64-encoded file contents keyed by relative path. Can be called at any time after construction, including after run().