gumloop 0.3.2__tar.gz → 0.3.4__tar.gz

{gumloop-0.3.2 → gumloop-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gumloop
-Version: 0.3.2
+Version: 0.3.4
 Summary: Python client for the Gumloop API
 Project-URL: Homepage, https://github.com/gumloop/gumloop-py
 Project-URL: Bug Tracker, https://github.com/gumloop/gumloop-py/issues
@@ -12,6 +12,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
+Requires-Dist: click>=8.0
 Requires-Dist: httpx-sse>=0.4.0
 Requires-Dist: httpx>=0.24.1
 Requires-Dist: keyring>=24

{gumloop-0.3.2 → gumloop-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gumloop"
-version = "0.3.2"
+version = "0.3.4"
 description = "Python client for the Gumloop API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -28,6 +28,7 @@ dependencies = [
     "pydantic>=2.0.0",
     "questionary>=2.0",
     "rich",
+    "click>=8.0",
     "typer>=0.25.1",
 ]
 

{gumloop-0.3.2 → gumloop-0.3.4}/src/gumloop/__init__.py

@@ -6,7 +6,7 @@ from gumloop.errors import AuthenticationError
 from gumloop.errors import GumloopError
 from gumloop.oauth import OAuth
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"
 __all__ = [
     "APIStatusError",
     "AsyncGumloop",

{gumloop-0.3.2 → gumloop-0.3.4}/src/gumloop/_client.py

@@ -15,12 +15,14 @@ from gumloop.resources import Agents
 from gumloop.resources import Artifacts
 from gumloop.resources import AsyncAgents
 from gumloop.resources import AsyncArtifacts
+from gumloop.resources import AsyncBrain
 from gumloop.resources import AsyncChat
 from gumloop.resources import AsyncMCP
 from gumloop.resources import AsyncModels
 from gumloop.resources import AsyncSessions
 from gumloop.resources import AsyncSkills
 from gumloop.resources import AsyncTeams
+from gumloop.resources import Brain
 from gumloop.resources import Chat
 from gumloop.resources import Models
 from gumloop.resources import Sessions
@@ -41,9 +43,9 @@ def _derive_stream_base_url(base_url: str) -> str:
 class Gumloop:
     """Sync Gumloop SDK client. Composes an :class:`HttpClient` with the
     resource classes (``agents``, ``sessions``, ``mcp``, ``teams``,
-    ``skills``, ``artifacts``, ``models``). The :attr:`oauth` attribute
-    holds OAuth helpers — kept off the transport because it bootstraps the
-    bearer token rather than consuming one."""
+    ``skills``, ``artifacts``, ``brain``, ``models``). The :attr:`oauth`
+    attribute holds OAuth helpers — kept off the transport because it
+    bootstraps the bearer token rather than consuming one."""
 
     def __init__(
         self,
@@ -85,6 +87,7 @@ class Gumloop:
         self.teams = Teams(self._http)
         self.skills = Skills(self._http)
         self.artifacts = Artifacts(self._http)
+        self.brain = Brain(self._http)
         self.oauth = OAuth(base_url=self.base_url, timeout=self.timeout)
 
     def close(self) -> None:
@@ -137,6 +140,7 @@ class AsyncGumloop:
         self.teams = AsyncTeams(self._http)
         self.skills = AsyncSkills(self._http)
         self.artifacts = AsyncArtifacts(self._http)
+        self.brain = AsyncBrain(self._http)
         self.oauth = OAuth(base_url=self.base_url, timeout=self.timeout)
 
     async def __aenter__(self) -> AsyncGumloop:

{gumloop-0.3.2 → gumloop-0.3.4}/src/gumloop/_http.py

@@ -110,6 +110,9 @@ class HttpClient:
     ) -> Any:
         return self._request("PATCH", path, json=json, data=_omit_none_params(data), files=files)
 
+    def put(self, path: str, *, json: Any = None) -> Any:
+        return self._request("PUT", path, json=json)
+
     def delete(self, path: str) -> Any:
         return self._request("DELETE", path)
 
@@ -251,6 +254,9 @@ class AsyncHttpClient:
     ) -> Any:
         return await self._request("PATCH", path, json=json, data=_omit_none_params(data), files=files)
 
+    async def put(self, path: str, *, json: Any = None) -> Any:
+        return await self._request("PUT", path, json=json)
+
     async def delete(self, path: str) -> Any:
         return await self._request("DELETE", path)
 

{gumloop-0.3.2 → gumloop-0.3.4}/src/gumloop/cli/commands/agents.py

@@ -144,6 +144,10 @@ def create_agent(
         str | None,
         typer.Option("--tools-file", help="Path to a JSON file containing the tools array."),
     ] = None,
+    skill_ids: Annotated[
+        str | None,
+        typer.Option("--skill-ids", help="Comma-separated ids of existing skills to attach."),
+    ] = None,
     json_output: Annotated[
         bool,
         typer.Option("--json", help="Print the raw SDK response as JSON."),
@@ -186,6 +190,12 @@ def create_agent(
                     raise GumloopError("Tools JSON must be an array at the top level.")
                 tools = parsed
 
+        parsed_skill_ids = (
+            [skill_id.strip() for skill_id in skill_ids.split(",") if skill_id.strip()]
+            if skill_ids is not None
+            else None
+        )
+
         response = cli.call_with_refresh(
             lambda client: client.agents.create(
                 name=name,
@@ -193,6 +203,7 @@ def create_agent(
                 description=description,
                 system_prompt=resolved_prompt,
                 tools=tools,
+                skill_ids=parsed_skill_ids,
                 team_id=cli.effective_team_id,
             )
         )
@@ -233,11 +244,23 @@ def update_agent(
     ] = None,
     tools_json: Annotated[
         str | None,
-        typer.Option("--tools-json", help="Inline JSON array of tool config objects."),
+        typer.Option(
+            "--tools-json",
+            help=(
+                "Inline JSON array of tool config objects."
+                " (legacy: replaces the entire tools list; prefer attach-mcp-server/detach-mcp-server)"
+            ),
+        ),
     ] = None,
     tools_file: Annotated[
         str | None,
-        typer.Option("--tools-file", help="Path to a JSON file containing the tools array."),
+        typer.Option(
+            "--tools-file",
+            help=(
+                "Path to a JSON file containing the tools array."
+                " (legacy: replaces the entire tools list; prefer attach-mcp-server/detach-mcp-server)"
+            ),
+        ),
     ] = None,
     is_active: Annotated[
         bool | None,
@@ -303,3 +326,125 @@ def update_agent(
         return
 
     console.print(f"[green]Updated agent[/green] {agent_id}")
+
+
+@agents_app.command(
+    "attach-skills",
+    epilog="Example:\n  gumloop agents attach-skills agent_abc skill_1 skill_2",
+)
+def attach_skills(
+    ctx: typer.Context,
+    agent_id: Annotated[str, typer.Argument(help="ID of the agent to attach skills to.")],
+    skill_ids: Annotated[list[str], typer.Argument(help="One or more skill ids to attach.")],
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print the raw SDK response as JSON."),
+    ] = False,
+) -> None:
+    """Attach one or more skills to an agent (idempotent)."""
+    cli: CliContext = ctx.obj
+    try:
+        response = cli.call_with_refresh(lambda client: client.agents.attach_skills(agent_id, skill_ids))
+    except GumloopError as error:
+        exit_with_error(error, json_output=json_output)
+
+    if json_output:
+        print_json(response)
+        return
+
+    console.print(f"[green]Attached[/green] {len(response.attached)} skill(s) to {agent_id}")
+    if response.already_attached:
+        console.print(f"  Already attached: {', '.join(response.already_attached)}", markup=False, highlight=False)
+
+
+@agents_app.command(
+    "detach-skills",
+    epilog="Example:\n  gumloop agents detach-skills agent_abc skill_1 skill_2",
+)
+def detach_skills(
+    ctx: typer.Context,
+    agent_id: Annotated[str, typer.Argument(help="ID of the agent to detach skills from.")],
+    skill_ids: Annotated[list[str], typer.Argument(help="One or more skill ids to detach.")],
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print the raw SDK response as JSON."),
+    ] = False,
+) -> None:
+    """Detach one or more skills from an agent (idempotent)."""
+    cli: CliContext = ctx.obj
+    try:
+        response = cli.call_with_refresh(lambda client: client.agents.detach_skills(agent_id, skill_ids))
+    except GumloopError as error:
+        exit_with_error(error, json_output=json_output)
+
+    if json_output:
+        print_json(response)
+        return
+
+    console.print(f"[green]Detached[/green] {len(response.detached)} skill(s) from {agent_id}")
+    if response.already_detached:
+        console.print(f"  Already detached: {', '.join(response.already_detached)}", markup=False, highlight=False)
+
+
+@agents_app.command(
+    "attach-mcp-server",
+    epilog="Example:\n  gumloop agents attach-mcp-server agent_abc gmail --approval-mode off",
+)
+def attach_mcp_server(
+    ctx: typer.Context,
+    agent_id: Annotated[str, typer.Argument(help="ID of the agent to attach the MCP server to.")],
+    server_id: Annotated[str, typer.Argument(help="ID of the MCP server to attach.")],
+    approval_mode: Annotated[
+        str | None,
+        typer.Option("--approval-mode", help="Tool-call approval mode for this server."),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print the raw SDK response as JSON."),
+    ] = False,
+) -> None:
+    """Attach an MCP server to an agent, or update its config (idempotent upsert)."""
+    cli: CliContext = ctx.obj
+    try:
+        response = cli.call_with_refresh(
+            lambda client: client.agents.attach_mcp_server(agent_id, server_id, approval_mode=approval_mode)
+        )
+    except GumloopError as error:
+        exit_with_error(error, json_output=json_output)
+
+    if json_output:
+        print_json(response)
+        return
+
+    verb = "Attached" if response.created else "Updated"
+    console.print(f"[green]{verb}[/green] MCP server {escape_markup(server_id)} on {agent_id}")
+    if response.auth_status:
+        console.print(f"  Auth status: {response.auth_status}", markup=False, highlight=False)
+
+
+@agents_app.command(
+    "detach-mcp-server",
+    epilog="Example:\n  gumloop agents detach-mcp-server agent_abc gmail",
+)
+def detach_mcp_server(
+    ctx: typer.Context,
+    agent_id: Annotated[str, typer.Argument(help="ID of the agent to detach the MCP server from.")],
+    server_id: Annotated[str, typer.Argument(help="ID of the MCP server to detach.")],
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print the raw SDK response as JSON."),
+    ] = False,
+) -> None:
+    """Detach an MCP server from an agent (idempotent)."""
+    cli: CliContext = ctx.obj
+    try:
+        response = cli.call_with_refresh(lambda client: client.agents.detach_mcp_server(agent_id, server_id))
+    except GumloopError as error:
+        exit_with_error(error, json_output=json_output)
+
+    if json_output:
+        print_json(response)
+        return
+
+    console.print(f"[green]Detached[/green] MCP server {escape_markup(server_id)} from {agent_id}")
+    console.print(f"  detached: {'true' if response.detached else 'false'}", markup=False, highlight=False)

gumloop-0.3.4/src/gumloop/cli/commands/brain.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from gumloop import GumloopError
+from gumloop.cli.console import console
+from gumloop.cli.console import print_json
+from gumloop.cli.context import CliContext
+from gumloop.cli.errors import exit_with_error
+
+brain_app = typer.Typer(help="Search your Company Brain.", no_args_is_help=True, rich_markup_mode="rich")
+
+
+@brain_app.command(
+    "search",
+    epilog=(
+        "Examples:\n"
+        '  gumloop brain search "onboarding process"\n'
+        '  gumloop brain search "pricing" --limit 5 --source notion --json'
+    ),
+)
+def search_brain(
+    ctx: typer.Context,
+    query: Annotated[str, typer.Argument(help="Search query.")],
+    limit: Annotated[
+        int | None,
+        typer.Option("--limit", help="Maximum number of results to return (1-50)."),
+    ] = None,
+    source: Annotated[
+        list[str] | None,
+        typer.Option("--source", help="Filter by source type (repeatable), e.g. notion, google_drive, slack."),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Print the raw SDK response as JSON."),
+    ] = False,
+) -> None:
+    """Search indexed Company Brain sources."""
+    cli: CliContext = ctx.obj
+    try:
+        response = cli.call_with_refresh(
+            lambda client: client.brain.search(query, limit=limit, source_type=source or None)
+        )
+    except GumloopError as error:
+        exit_with_error(error, json_output=json_output)
+
+    if json_output:
+        print_json(response)
+        return
+
+    if not response.results:
+        console.print("No results found.")
+        return
+
+    console.print("SCORE", "SOURCE", "TITLE", "URL", sep="\t", soft_wrap=True)
+    for result in response.results:
+        console.print(
+            "" if result.score is None else f"{result.score:.3f}",
+            result.source or "",
+            result.title or "",
+            result.url or "",
+            sep="\t",
+            soft_wrap=True,
+        )

{gumloop-0.3.2 → gumloop-0.3.4}/src/gumloop/cli/main.py

@@ -11,6 +11,7 @@ from gumloop.cli.commands.agents import agents_app
 from gumloop.cli.commands.artifacts import artifacts_app
 from gumloop.cli.commands.auth import login as login_command
 from gumloop.cli.commands.auth import logout as logout_command
+from gumloop.cli.commands.brain import brain_app
 from gumloop.cli.commands.chat import chat_app
 from gumloop.cli.commands.mcp import mcp_app
 from gumloop.cli.commands.sessions import sessions_app
@@ -97,6 +98,7 @@ app.add_typer(sessions_app, name="sessions")
 app.add_typer(skills_app, name="skills")
 app.add_typer(artifacts_app, name="artifacts")
 app.add_typer(chat_app, name="chat")
+app.add_typer(brain_app, name="brain")
 
 
 def _require_supported_platform() -> None:

{gumloop-0.3.2 → gumloop-0.3.4}/src/gumloop/resources/__init__.py

@@ -6,6 +6,8 @@ from gumloop.resources.agents import AsyncModels
 from gumloop.resources.agents import Models
 from gumloop.resources.artifacts import Artifacts
 from gumloop.resources.artifacts import AsyncArtifacts
+from gumloop.resources.brain import AsyncBrain
+from gumloop.resources.brain import Brain
 from gumloop.resources.chat import AsyncChat
 from gumloop.resources.chat import Chat
 from gumloop.resources.mcp import MCP
@@ -23,12 +25,14 @@ __all__ = [
     "Artifacts",
     "AsyncAgents",
     "AsyncArtifacts",
+    "AsyncBrain",
     "AsyncChat",
     "AsyncMCP",
     "AsyncModels",
     "AsyncSessions",
     "AsyncSkills",
     "AsyncTeams",
+    "Brain",
     "Chat",
     "Models",
     "Sessions",

{gumloop-0.3.2 → gumloop-0.3.4}/src/gumloop/resources/agents.py

@@ -1,19 +1,29 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
+from collections.abc import Sequence
 from typing import Any
 
 from gumloop._http import AsyncHttpClient
 from gumloop._http import HttpClient
 from gumloop.types import AgentCreateRequest
 from gumloop.types import AgentListResponse
+from gumloop.types import AgentMcpServerDetachResponse
+from gumloop.types import AgentMcpServerResponse
+from gumloop.types import AgentMcpServersResponse
 from gumloop.types import AgentResponse
+from gumloop.types import AgentSkillsResponse
 from gumloop.types import AgentUpdateRequest
 from gumloop.types import EvaluationConfigResponse
 from gumloop.types import EvaluationConfigUpdateRequest
 from gumloop.types import EvaluationResultListResponse
 from gumloop.types import EvaluationResultResponse
 from gumloop.types import ModelListResponse
+from gumloop.types import SkillListResponse
+
+
+def _skill_id_list(skill_ids: str | Sequence[str]) -> list[str]:
+    return [skill_ids] if isinstance(skill_ids, str) else list(skill_ids)
 
 
 class Agents:
@@ -49,10 +59,48 @@ class Agents:
         request: AgentUpdateRequest | Mapping[str, Any] | None = None,
         **kwargs: Any,
     ) -> AgentResponse:
+        """``tools`` replaces the entire list when provided (legacy bulk path); prefer
+        attach_mcp_server/detach_mcp_server for individual MCP servers and
+        attach_skills/detach_skills for skills."""
         return AgentResponse.model_validate(
             self._client.patch(f"agents/{agent_id}", json=AgentUpdateRequest.build(request, **kwargs))
         )
 
+    def attach_skills(self, agent_id: str, skill_ids: str | Sequence[str]) -> AgentSkillsResponse:
+        """Attach skills to an agent. Idempotent: safe to retry, already-attached ids are reported."""
+        return AgentSkillsResponse.model_validate(
+            self._client.patch(f"agents/{agent_id}/skills", json={"attach": _skill_id_list(skill_ids)})
+        )
+
+    def detach_skills(self, agent_id: str, skill_ids: str | Sequence[str]) -> AgentSkillsResponse:
+        """Detach skills from an agent. Idempotent: safe to retry, already-detached ids are reported."""
+        return AgentSkillsResponse.model_validate(
+            self._client.patch(f"agents/{agent_id}/skills", json={"detach": _skill_id_list(skill_ids)})
+        )
+
+    def list_skills(self, agent_id: str, **kwargs: Any) -> SkillListResponse:
+        return SkillListResponse.model_validate(
+            self._client.get("skills", params={"agent_id": agent_id, **kwargs})
+        )
+
+    def attach_mcp_server(self, agent_id: str, server_id: str, **config: Any) -> AgentMcpServerResponse:
+        """Attach an MCP server, or update its config if already attached (idempotent upsert)."""
+        return AgentMcpServerResponse.model_validate(
+            self._client.put(
+                f"agents/{agent_id}/mcp-servers/{server_id}",
+                json={k: v for k, v in config.items() if v is not None},
+            )
+        )
+
+    def detach_mcp_server(self, agent_id: str, server_id: str) -> AgentMcpServerDetachResponse:
+        """Detach an MCP server from an agent. Idempotent: safe to retry."""
+        return AgentMcpServerDetachResponse.model_validate(
+            self._client.delete(f"agents/{agent_id}/mcp-servers/{server_id}")
+        )
+
+    def list_mcp_servers(self, agent_id: str) -> AgentMcpServersResponse:
+        return AgentMcpServersResponse.model_validate(self._client.get(f"agents/{agent_id}/mcp-servers"))
+
     def get_evaluation_config(self, agent_id: str) -> EvaluationConfigResponse:
         return EvaluationConfigResponse.model_validate(self._client.get(f"agents/{agent_id}/evaluation-config"))
 
@@ -133,9 +181,43 @@ class AsyncAgents:
         request: AgentUpdateRequest | Mapping[str, Any] | None = None,
         **kwargs: Any,
     ) -> AgentResponse:
+        """``tools`` replaces the entire list when provided (legacy bulk path); prefer
+        attach_mcp_server/detach_mcp_server for individual MCP servers and
+        attach_skills/detach_skills for skills."""
         data = await self._client.patch(f"agents/{agent_id}", json=AgentUpdateRequest.build(request, **kwargs))
         return AgentResponse.model_validate(data)
 
+    async def attach_skills(self, agent_id: str, skill_ids: str | Sequence[str]) -> AgentSkillsResponse:
+        """Attach skills to an agent. Idempotent: safe to retry, already-attached ids are reported."""
+        data = await self._client.patch(f"agents/{agent_id}/skills", json={"attach": _skill_id_list(skill_ids)})
+        return AgentSkillsResponse.model_validate(data)
+
+    async def detach_skills(self, agent_id: str, skill_ids: str | Sequence[str]) -> AgentSkillsResponse:
+        """Detach skills from an agent. Idempotent: safe to retry, already-detached ids are reported."""
+        data = await self._client.patch(f"agents/{agent_id}/skills", json={"detach": _skill_id_list(skill_ids)})
+        return AgentSkillsResponse.model_validate(data)
+
+    async def list_skills(self, agent_id: str, **kwargs: Any) -> SkillListResponse:
+        data = await self._client.get("skills", params={"agent_id": agent_id, **kwargs})
+        return SkillListResponse.model_validate(data)
+
+    async def attach_mcp_server(self, agent_id: str, server_id: str, **config: Any) -> AgentMcpServerResponse:
+        """Attach an MCP server, or update its config if already attached (idempotent upsert)."""
+        data = await self._client.put(
+            f"agents/{agent_id}/mcp-servers/{server_id}",
+            json={k: v for k, v in config.items() if v is not None},
+        )
+        return AgentMcpServerResponse.model_validate(data)
+
+    async def detach_mcp_server(self, agent_id: str, server_id: str) -> AgentMcpServerDetachResponse:
+        """Detach an MCP server from an agent. Idempotent: safe to retry."""
+        data = await self._client.delete(f"agents/{agent_id}/mcp-servers/{server_id}")
+        return AgentMcpServerDetachResponse.model_validate(data)
+
+    async def list_mcp_servers(self, agent_id: str) -> AgentMcpServersResponse:
+        data = await self._client.get(f"agents/{agent_id}/mcp-servers")
+        return AgentMcpServersResponse.model_validate(data)
+
     async def get_evaluation_config(self, agent_id: str) -> EvaluationConfigResponse:
         data = await self._client.get(f"agents/{agent_id}/evaluation-config")
         return EvaluationConfigResponse.model_validate(data)

gumloop-0.3.4/src/gumloop/resources/brain.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Any
+
+from gumloop._http import AsyncHttpClient
+from gumloop._http import HttpClient
+from gumloop.types import BrainSearchRequest
+from gumloop.types import BrainSearchResponse
+
+
+class Brain:
+    def __init__(self, client: HttpClient) -> None:
+        self._client = client
+
+    def search(
+        self,
+        query: str,
+        *,
+        limit: int | None = None,
+        source_type: list[str] | None = None,
+        **kwargs: Any,
+    ) -> BrainSearchResponse:
+        return BrainSearchResponse.model_validate(
+            self._client.post(
+                "brain/search",
+                json=BrainSearchRequest.build(query=query, limit=limit, source_type=source_type, **kwargs),
+            )
+        )
+
+
+class AsyncBrain:
+    def __init__(self, client: AsyncHttpClient) -> None:
+        self._client = client
+
+    async def search(
+        self,
+        query: str,
+        *,
+        limit: int | None = None,
+        source_type: list[str] | None = None,
+        **kwargs: Any,
+    ) -> BrainSearchResponse:
+        data = await self._client.post(
+            "brain/search",
+            json=BrainSearchRequest.build(query=query, limit=limit, source_type=source_type, **kwargs),
+        )
+        return BrainSearchResponse.model_validate(data)

{gumloop-0.3.2 → gumloop-0.3.4}/src/gumloop/types.py

@@ -53,6 +53,7 @@ class AgentCreateRequest(_Model):
     system_prompt: str | None = None
     tools: list[dict[str, Any]] = Field(default_factory=list)
     resources: list[dict[str, Any]] = Field(default_factory=list)
+    skill_ids: list[str] | None = None
     metadata: dict[str, Any] | None = None
     folder_id: str | None = None
     is_active: bool = True
@@ -80,6 +81,7 @@ class Agent(_Model):
     is_active: bool = False
     tools: list[dict[str, Any]] = Field(default_factory=list)
     resources: list[dict[str, Any]] = Field(default_factory=list)
+    skill_ids: list[str] | None = None
     metadata: dict[str, Any] = Field(default_factory=dict)
     model_name: str | None = None
     system_prompt: str | None = None
@@ -90,6 +92,33 @@ class Agent(_Model):
     creator: CreatorPayload | None = None
 
 
+class AgentSkillsResponse(_Model):
+    agent_id: str
+    skill_ids: list[str] = Field(default_factory=list)
+    attached: list[str] = Field(default_factory=list)
+    detached: list[str] = Field(default_factory=list)
+    already_attached: list[str] = Field(default_factory=list)
+    already_detached: list[str] = Field(default_factory=list)
+
+
+class AgentMcpServerResponse(_Model):
+    agent_id: str
+    mcp_server: dict[str, Any] = Field(default_factory=dict)
+    created: bool = False
+    auth_status: str | None = None
+
+
+class AgentMcpServerDetachResponse(_Model):
+    agent_id: str
+    server_id: str
+    detached: bool = False
+
+
+class AgentMcpServersResponse(_Model):
+    agent_id: str
+    mcp_servers: list[dict[str, Any]] = Field(default_factory=list)
+
+
 class AgentResponse(_Model):
     agent: Agent
 
@@ -236,6 +265,35 @@ class SkillDownloadResponse(_Model):
     major_version: int | None = None
 
 
+# ---------------------------------------------------------------------------
+# Brain types
+# ---------------------------------------------------------------------------
+
+
+class BrainSearchRequest(_Model):
+    query: str
+    limit: int | None = None
+    source_type: list[str] | None = Field(default=None, min_length=1)
+
+
+class BrainSearchResult(_Model):
+    document_id: str | None = None
+    source: str | None = None
+    title: str | None = None
+    content: str | None = None
+    url: str | None = None
+    score: float | None = None
+    updated_at: str | None = None
+    owner_name: str | None = None
+    owner_email: str | None = None
+    parent_title: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class BrainSearchResponse(_Model):
+    results: list[BrainSearchResult] = Field(default_factory=list)
+
+
 # ---------------------------------------------------------------------------
 # Artifact types
 # ---------------------------------------------------------------------------