Fu-Jie_openwebui-extensions/plugins/pipes/github-copilot-sdk/CUSTOM_AGENTS_REFERENCE.md

🤖 Custom Agents Reference (Copilot SDK Python)

This document explains how to create custom agent profiles using the SDK at:

• /Users/fujie/app/python/oui/copilot-sdk/python

and apply them in this pipe:

• plugins/pipes/github-copilot-sdk/github_copilot_sdk.py

---

1) What is a “Custom Agent” here?

In Copilot SDK Python, a custom agent is not a separate runtime class from the SDK itself. It is typically a session configuration bundle:

• model + reasoning level
• system message/persona
• tools exposure
• hooks lifecycle behavior
• user input strategy
• infinite session compaction strategy
• provider (optional BYOK)

So the practical implementation is:

1. Define an AgentProfile data structure.
2. Convert profile -> session_config.
3. Call client.create_session(session_config).

---

2) SDK capabilities you can use

From copilot-sdk/python/README.md, the key knobs are:

• model
• reasoning_effort
• tools
• system_message
• streaming
• provider
• infinite_sessions
• on_user_input_request
• hooks

These are enough to create different agent personas without forking core logic.

---

3) Recommended architecture in pipe

Use a profile registry + a single factory method.

from dataclasses import dataclass
from typing import Any, Callable, Optional

@dataclass
class AgentProfile:
    name: str
    model: str
    reasoning_effort: str = "medium"
    system_message: Optional[str] = None
    enable_tools: bool = True
    enable_openwebui_tools: bool = True
    enable_hooks: bool = False
    enable_user_input: bool = False
    infinite_sessions_enabled: bool = True
    compaction_threshold: float = 0.8
    buffer_exhaustion_threshold: float = 0.95

Then map profile -> session config:

def build_session_config(profile: AgentProfile, tools: list, hooks: dict, user_input_handler: Optional[Callable[..., Any]]):
    config = {
        "model": profile.model,
        "reasoning_effort": profile.reasoning_effort,
        "streaming": True,
        "infinite_sessions": {
            "enabled": profile.infinite_sessions_enabled,
            "background_compaction_threshold": profile.compaction_threshold,
            "buffer_exhaustion_threshold": profile.buffer_exhaustion_threshold,
        },
    }

    if profile.system_message:
        config["system_message"] = {"content": profile.system_message}

    if profile.enable_tools:
        config["tools"] = tools

    if profile.enable_hooks and hooks:
        config["hooks"] = hooks

    if profile.enable_user_input and user_input_handler:
        config["on_user_input_request"] = user_input_handler

    return config

---

4) Example profile presets

AGENT_PROFILES = {
    "builder": AgentProfile(
        name="builder",
        model="claude-sonnet-4.6",
        reasoning_effort="high",
        system_message="You are a precise coding agent. Prefer minimal, verifiable changes.",
        enable_tools=True,
        enable_hooks=True,
    ),
    "analyst": AgentProfile(
        name="analyst",
        model="gpt-5-mini",
        reasoning_effort="medium",
        system_message="You analyze and summarize with clear evidence mapping.",
        enable_tools=False,
        enable_hooks=False,
    ),
    "reviewer": AgentProfile(
        name="reviewer",
        model="claude-sonnet-4.6",
        reasoning_effort="high",
        system_message="Review diffs, identify risks, and propose minimal fixes.",
        enable_tools=True,
        enable_hooks=True,
    ),
}

---

5) Integrating with this pipe

In github_copilot_sdk.py:

1. Add a Valve like AGENT_PROFILE (default: builder).
2. Resolve profile from registry at runtime.
3. Build session_config from profile.
4. Merge existing valve toggles (ENABLE_TOOLS, ENABLE_OPENWEBUI_TOOLS) as final override.

Priority recommendation:

• explicit runtime override > valve toggle > profile default

This keeps backward compatibility while enabling profile-based behavior.

---

6) Hook strategy (safe defaults)

Use hooks only when needed:

• on_pre_tool_use: allow/deny tools, sanitize args
• on_post_tool_use: add short execution context
• on_user_prompt_submitted: normalize unsafe prompt patterns
• on_error_occurred: retry/skip/abort policy

Start with no-op hooks, then incrementally enforce policy.

---

7) Validation checklist

• Profile can be selected by valve and takes effect.
• Session created with expected model/reasoning.
• Tool availability matches profile + valve overrides.
• Hook handlers run only when enabled.
• Infinite-session compaction settings are applied.
• Fallback to default profile if unknown profile name is provided.

---

8) Anti-patterns to avoid

• Hardcoding profile behavior in multiple places.
• Mixing tool registration logic with prompt-format logic.
• Enabling expensive hooks for all profiles by default.
• Coupling profile name to exact model id with no fallback.

---

9) Minimal rollout plan

1. Add profile dataclass + registry.
2. Add one valve: AGENT_PROFILE.
3. Build session config factory.
4. Keep existing behavior as default profile.
5. Add 2 more profiles (analyst, reviewer) and test.

---

10) SDK gap analysis for current pipe (high-value missing features)

Current pipe already implements many advanced capabilities:

• SessionConfig with tools, system_message, infinite_sessions, provider, mcp_servers
• Session resume/create path
• list_models() cache path
• Attachments in session.send(...)
• Hook integration (currently on_post_tool_use)

Still missing (or partially implemented) high-value SDK features:

A. on_user_input_request handler (ask-user loop)

Why valuable

• Enables safe clarification for ambiguous tasks instead of hallucinated assumptions.

Current state

• Not wired into create_session(...).

Implementation idea

• Add valves:
  • ENABLE_USER_INPUT_REQUEST: bool
  • DEFAULT_USER_INPUT_ANSWER: str
• Add a handler function and pass:
  • session_params["on_user_input_request"] = handler

B. Full lifecycle hooks (beyond on_post_tool_use)

Why valuable

• Better policy control and observability.

Current state

• Only on_post_tool_use implemented.

Implementation idea

• Add optional handlers for:
  • on_pre_tool_use
  • on_user_prompt_submitted
  • on_session_start
  • on_session_end
  • on_error_occurred

C. Provider type coverage gap (azure)

Why valuable

• Azure OpenAI users cannot configure provider type natively.

Current state

• Valve type only allows openai | anthropic.

Implementation idea

• Extend valve enum to include azure.
• Add BYOK_AZURE_API_VERSION valve.
• Build provider payload with azure block when selected.

D. Client transport options exposure (cli_url, use_stdio, port)

Why valuable

• Enables remote/shared Copilot server and tuning transport mode.

Current state

• _build_client_config sets cli_path/cwd/config_dir/log_level/env, but not transport options.

Implementation idea

• Add valves:
  • COPILOT_CLI_URL
  • COPILOT_USE_STDIO
  • COPILOT_PORT
• Conditionally inject into client_config.

E. Foreground session lifecycle APIs

Why valuable

• Better multi-session UX and control in TUI/server mode.

Current state

• No explicit usage of:
  • get_foreground_session_id()
  • set_foreground_session_id()
  • client.on("session.foreground", ...)

Implementation idea

• Optional debug/admin feature only.
• Add event bridge for lifecycle notifications.

---

11) Recommended implementation priority

1. on_user_input_request (highest value / low risk)
2. Full lifecycle hooks (high value / medium risk)
3. Azure provider support (high value for enterprise users)
4. Client transport valves (cli_url/use_stdio/port)
5. Foreground session APIs (optional advanced ops)