API Reference

CopilotAgent(name: str = 'copilot', model: str | None = None, reasoning_effort: Literal['low', 'medium', 'high', 'xhigh'] | None = None, instructions: str | None = None, system_message_mode: Literal['append', 'replace'] = 'append', working_directory: str | None = None, allowed_tools: list[str] | None = None, excluded_tools: list[str] | None = None, max_turns: int = 25, timeout_s: float = 300.0, auto_confirm: bool = True, mcp_servers: dict[str, Any] = dict(), custom_agents: list[dict[str, Any]] = list(), skill_directories: list[str] = list(), disabled_skills: list[str] = list(), extra_config: dict[str, Any] = dict()) dataclass

Configuration for a GitHub Copilot agent test.

Maps to the Copilot SDK's SessionConfig. User-facing field names are kept intuitive (e.g. instructions), while build_session_config() maps them to the SDK's actual system_message TypedDict.

The SDK's SessionConfig has no maxTurns field — turn limits are enforced externally by the runner via timeout_s.

Example

Minimal

CopilotAgent()

With instructions and model

CopilotAgent( name="security-reviewer", model="claude-sonnet-4", instructions="Review code for security vulnerabilities.", )

With custom tools and references

CopilotAgent( name="file-creator", instructions="Create files as requested.", working_directory="/tmp/workspace", allowed_tools=["create_file", "read_file"], )

build_session_config() -> dict[str, Any]

Build a SessionConfig dict for the Copilot SDK.

Returns a dict compatible with CopilotClient.create_session(). Only includes non-None/non-default fields to avoid overriding SDK defaults.

SDK field mapping (Python snake_case TypedDict keys): instructions → system_message: {mode, content} allowed_tools → available_tools excluded_tools → excluded_tools reasoning_effort → reasoning_effort working_directory → working_directory mcp_servers → mcp_servers custom_agents → custom_agents skill_directories → skill_directories disabled_skills → disabled_skills

Note: max_turns is NOT part of SessionConfig — the runner enforces turn limits externally.

CopilotResult(turns: list[Turn] = list(), success: bool = True, error: str | None = None, duration_ms: float = 0.0, usage: list[UsageInfo] = list(), reasoning_traces: list[str] = list(), subagent_invocations: list[SubagentInvocation] = list(), permission_requested: bool = False, permissions: list[dict[str, Any]] = list(), model_used: str | None = None, raw_events: list[Any] = list()) dataclass

Result of running a prompt against GitHub Copilot.

Captures the full event stream from the SDK, including tool calls, reasoning traces, subagent routing, permissions, and token usage.

Example

result = await copilot_run(agent, "Create hello.py") assert result.success assert result.tool_was_called("create_file") assert "hello" in result.final_response.lower()

final_response: str | None property

Get the last assistant response.

all_responses: list[str] property

Get all assistant responses.

all_tool_calls: list[ToolCall] property

Get all tool calls across all turns.

tool_names_called: set[str] property

Get set of all tool names that were called.

total_input_tokens: int property

Total input tokens across all model turns.

total_output_tokens: int property

Total output tokens across all model turns.

total_tokens: int property

Total tokens (input + output) across all model turns.

total_cost_usd: float property

Total cost in USD across all model turns.

token_usage: dict[str, int] property

Token usage dict compatible with pytest-aitest's AgentResult.

cost_usd: float property

Cost in USD, compatible with pytest-aitest's AgentResult.

tool_was_called(name: str) -> bool

Check if a specific tool was called.

tool_call_count(name: str) -> int

Count how many times a specific tool was called.

tool_calls_for(name: str) -> list[ToolCall]

Get all calls to a specific tool.