from ai_infra.llm import CopilotAgentComputer automation agent backed by the GitHub Copilot CLI runtime. Delegates autonomous task execution to the Copilot CLI, which manages its own LLM calls, planning loop, and tool use. This is not an LLM provider — it is a runtime you direct with plain-language tasks. The agent lazily starts the CLI process on first use and reuses it across multiple ``run()`` / ``stream()`` calls. Use the async context manager for explicit lifecycle control. Example — one-liner task:: from ai_infra import CopilotAgent result = await CopilotAgent(cwd="/my/project").run( "Add docstrings to every public function" ) print(result.content) Example — multi-turn session (conversation memory):: agent = CopilotAgent() r1 = await agent.run("Explore the auth module", session_id="s1") r2 = await agent.run("Now add tests for it", session_id="s1") Example — streaming with live tool output:: async for event in agent.stream("Run the test suite and fix failures"): if event.type == "token": print(event.content, end="", flush=True) elif event.type == "tool_start": print(f"\n→ {event.tool}") elif event.type == "tool_output": print(event.content, end="", flush=True) Example — custom tool:: @copilot_tool async def lookup_issue(id: str) -> str: "Fetch an issue from Linear." return await linear.get(id) agent = CopilotAgent(tools=[lookup_issue]) await agent.run("Fix the bug described in issue LIN-42") Example — read-only analysis (no writes, no shell):: agent = CopilotAgent(permissions=PermissionMode.READ_ONLY) result = await agent.run("Audit for OWASP Top 10 vulnerabilities") Example — BYOK (no GitHub Copilot subscription required):: agent = CopilotAgent( model="gpt-4.1", provider={ "type": "openai", "base_url": "https://api.openai.com/v1", "api_key": os.environ["OPENAI_API_KEY"], }, ) Example — with ai-infra callbacks (LoggingCallbacks, MetricsCallbacks, etc.):: from ai_infra.callbacks import LoggingCallbacks agent = CopilotAgent(callbacks=LoggingCallbacks()) Example — context manager for explicit cleanup:: async with CopilotAgent(cwd="/my/project") as agent: result = await agent.run("Refactor the database layer")
model: Model to use (e.g. ``"claude-sonnet-4-5"``, ``"gpt-4.1"``). When using BYOK ``provider``, this is required. Otherwise the Copilot CLI selects the default model. cwd: Working directory for the CLI process. Defaults to the current directory. Set this to the project root when automating file tasks. github_token: GitHub token for authentication. Takes priority over the ``COPILOT_GITHUB_TOKEN`` / ``GH_TOKEN`` environment variables and the CLI's stored login credentials. provider: BYOK provider configuration dict for non-GitHub LLM access. Supports ``"openai"``, ``"azure"``, and ``"anthropic"`` types. When set, ``model`` is required. Example: ``{"type": "openai", "base_url": "...", "api_key": "..."}`` tools: Python callables decorated with ``@copilot_tool``, or raw Copilot SDK ``Tool`` objects, to expose to the agent. permissions: Controls which tools the agent may invoke. Pass a ``PermissionMode`` enum value for built-in policies, or a callable ``(tool_name: str, arguments: dict) -> bool`` for custom logic. Default: ``PermissionMode.AUTO_APPROVE``. skill_dirs: Directories containing skill subdirectories (each with a ``SKILL.md`` file). Skills are prompt modules injected as context. mcp_servers: MCP server configurations keyed by server name. Example: ``{"filesystem": {"type": "local", "command": "npx", "args": ["-y", "@mcp/server-filesystem", "/tmp"], "tools": ["*"]}}`` custom_agents: Named sub-agent definitions for automatic task delegation. Each entry: ``{"name": str, "prompt": str, "tools": list[str]}``. system_message: Override the default system prompt for the session. streaming: Enable streaming delta events from the CLI (required for ``stream()``). Default: ``True``. infinite_context: Enable automatic context compaction when the context window approaches capacity. Default: ``True``. callbacks: ai-infra ``Callbacks`` instance (e.g. ``LoggingCallbacks()``, ``MetricsCallbacks()``). Copilot events are bridged to the standard ``ToolStartEvent``, ``ToolEndEvent``, ``LLMTokenEvent`` callbacks. reasoning_effort: Chain-of-thought depth for models that support it. One of ``"low"``, ``"medium"``, ``"high"``, ``"xhigh"``. Call ``list_models()`` to check which models accept this option. on_list_models: Custom handler for ``CopilotClient.list_models()``. When provided, the CLI's built-in model list RPC is replaced entirely. Return a list of ``ModelInfo`` objects describing your provider's models. Essential for BYOK to declare reasoning support:: from ai_infra.llm.agents.copilot import ModelInfo agent = CopilotAgent( provider={"type": "anthropic", ...}, on_list_models=lambda: [ModelInfo( id="claude-sonnet-4-5", name="Claude Sonnet 4.5", capabilities=ModelCapabilities( supports=ModelSupports(vision=True, reasoning_effort=True), limits=ModelLimits(max_context_window_tokens=200_000), ), )], ) on_user_input: Async callable invoked when the agent needs to ask the user a question (enables Copilot's ``ask_user`` tool). Receives ``(request, invocation)`` where ``request["question"]`` is the question text and ``request.get("choices")`` is an optional list. Must return ``{"answer": str, "wasFreeform": bool}``. hooks: Power-user hook dict for session lifecycle interception. Keys are hook names (``"on_session_start"``, ``"on_user_prompt_submitted"``, ``"on_post_tool_use"``, ``"on_session_end"``, ``"on_error_occurred"``). Any ``"on_pre_tool_use"`` key here is merged with—and takes precedence over—the built-in permission hook derived from ``permissions``. telemetry: OpenTelemetry config for the CLI subprocess. Example: ``{"otlp_endpoint": "http://localhost:4318"}``. Providing this dict enables tracing — no separate flag required. external_server: URL of an already-running Copilot CLI server (e.g. ``"localhost:3000"``). When set, a new subprocess is not spawned and the ``cli_path`` / ``env`` / ``github_token`` params are ignored. cli_path: Absolute path to a specific ``copilot`` CLI binary. Defaults to the bundled binary from the SDK. env: Extra environment variables for the CLI subprocess. Merged with the inherited process environment. disabled_skills: Skill names to exclude when ``skill_dirs`` are provided (e.g. ``["slow-research", "web-fetch"]``). initial_agent: Name of the custom agent to pre-select when the session starts. Must match a ``name`` in ``custom_agents``. Equivalent to calling ``agent.select()`` after creation but avoids the extra round-trip.