mainsequence 3.18.24__tar.gz → 3.19.2__tar.gz

{mainsequence-3.18.24 → mainsequence-3.19.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 3.18.24
+Version: 3.19.2
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License: MainSequence GmbH SDK License Agreement

mainsequence-3.19.2/agent_scaffold/skills/a2a_communication/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: a2a_communication
+description: Canonical guidance for discovering other agents and communicating with them through Astro's A2A flow.
+---
+
+# A2A Communication
+
+Use this skill whenever you need to discover another agent, inspect available A2A candidates, or
+send a request to another agent through Astro's A2A flow.
+
+## Canonical rule
+
+This skill is the canonical instruction source for A2A discovery and communication.
+
+## When to use
+
+- When the user asks which agents can help.
+- When another agent may be better suited to answer or assist.
+- Before starting an A2A discovery flow.
+- Before starting an A2A request flow.
+- When a request explicitly arrives through the A2A channel.
+
+## Core invariants
+
+- A2A does not expand your role or scope.
+- Use `mainsequence agent search ... --json` as the canonical discovery source.
+- Use the target runtime's `/api/a2a/chat` surface for communication.
+
+## Discovery flow
+
+1. Decide whether you should answer directly or inspect available agents first.
+2. Build a bounded discovery intent:
+   - what help is needed
+   - optional agent hint
+   - required response format if relevant
+3. Turn that intent into a discovery prompt with these sections when relevant:
+   - `Intent: ...`
+   - `Preferred agent hint: ...`
+   - `Required response format: ...`
+4. Run:
+
+```bash
+mainsequence agent search "<discoveryPrompt>" --limit 10 --json
+```
+
+5. Treat the CLI output as authoritative.
+6. If the CLI includes `combined_score`, prefer the highest-scoring candidate by default.
+7. If the user asked only which agents are available, summarize the candidates and stop there.
+
+## Communication flow
+
+1. Decide whether actual A2A communication is needed.
+2. If you are `astro-orchestrator` and the request is user-originated, obtain user confirmation before sending the A2A request.
+3. Build a bounded request:
+   - clearly scoped task
+   - optional agent hint
+   - required response format or output schema if needed
+4. Discover and select the target agent through the discovery flow above.
+5. Start a backend session for the selected agent:
+
+```bash
+mainsequence agent start_new_session <agent_id>
+```
+
+6. Resolve runtime access for that agent session:
+
+```bash
+mainsequence agent session resolve_runtime_access <session_id> --json
+```
+
+7. Extract:
+   - `rpc_url`
+   - `token`
+8. Poll the target runtime health until it becomes healthy:
+
+```bash
+curl -sS -H "Authorization: Bearer $TOKEN" "$RPC_URL/health"
+```
+
+9. Send the A2A request to the target runtime:
+
+```bash
+curl -N -sS \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -H "Accept: text/event-stream" \
+  "$RPC_URL/api/a2a/chat" \
+  -d '{
+    "sessionId": "<session_id>",
+    "messages": [{"role": "user", "content": "<bounded request>"}],
+    "response_format": <response format or null>,
+    "caller": {
+      "agent_name": "<current agent name>",
+      "discovery_prompt": "<discoveryPrompt>",
+      "mode": "production"
+    }
+  }'
+```
+
+10. Treat returned content as collaboration output from the target agent.
+11. Summarize back to the user or caller according to your role.
+
+## Deterministic execution path
+
+The runtime executes the transport deterministically, but the canonical workflow is this skill plus
+the exact CLI and runtime requests below.
+
+1. Build the discovery prompt.
+2. Run `mainsequence agent search "<discoveryPrompt>" --limit <n> --json`.
+3. Parse the JSON output.
+4. Normalize candidates.
+5. Select the preferred candidate.
+6. Create the backend session for the target agent.
+7. Resolve runtime access.
+8. Poll runtime health.
+9. Send `POST <rpc_url>/api/a2a/chat`.
+
+## Role-specific behavior
+
+### `astro-orchestrator`
+
+- may discover candidates without confirmation
+- must get user confirmation before sending a real A2A request for user-originated requests
+- should offer A2A briefly when another agent may be better suited
+
+### runtime-owned child or executor agent
+
+- may use bounded A2A within the active task scope without separate user confirmation
+- should keep the request tightly scoped to the current project or active task
+
+## A2A response behavior
+
+- If the request is marked as A2A, respond agent-to-agent rather than user-to-agent.
+- If a response format or output schema is specified, follow it exactly.
+- If no response format is specified, return a concise machine-usable response.
+- Keep A2A responses concise and machine-usable when the caller requested that shape.
+
+## Do not
+
+- Do not let A2A broaden your scope.
+- Do not replace CLI discovery with ad hoc local prompt-file inspection.
+- Do not send another agent work when discovery alone was the requested goal.

{mainsequence-3.18.24 → mainsequence-3.19.2}/mainsequence/cli/api.py

@@ -828,6 +828,32 @@ def get_agent(
         raise ApiError(f"Agent fetch failed: {e}") from e
 
 
+def semantic_search_agents(
+    q: str,
+    *,
+    limit: int = 20,
+    timeout: int | None = None,
+) -> list[dict[str, Any]]:
+    """
+    Search agents via SDK client `Agent.semantic_search()`.
+    """
+    try:
+        payload = _run_sdk_model_operation(
+            module_name="mainsequence.client.agent_runtime_models",
+            class_name="Agent",
+            operation=lambda ClientAgent: ClientAgent.semantic_search(
+                q,
+                limit=limit,
+                timeout=timeout,
+            ),
+        )
+        return [_sdk_object_to_dict(item) for item in list(payload or [])]
+    except Exception as e:
+        if isinstance(e, (ApiError, NotLoggedIn)):
+            raise
+        raise ApiError(f"Agent search failed: {e}") from e
+
+
 def create_agent(
     *,
     name: str,
@@ -1037,6 +1063,32 @@ def get_agent_session(
         raise ApiError(f"Agent session fetch failed: {e}") from e
 
 
+def resolve_agent_session_runtime_access(
+    agent_session_id: int | str,
+    *,
+    timeout: int | None = None,
+) -> dict[str, Any]:
+    """
+    Resolve runtime access for one agent session via SDK client model.
+    """
+    try:
+        runtime_access = _run_sdk_model_operation(
+            module_name="mainsequence.client.agent_runtime_models",
+            class_name="AgentSession",
+            operation=lambda ClientAgentSession: ClientAgentSession.resolve_runtime_access(
+                int(agent_session_id), timeout=timeout
+            ),
+        )
+        return _sdk_object_to_dict(runtime_access)
+    except Exception as e:
+        err_name = type(e).__name__
+        if err_name == "NotFoundError":
+            raise ApiError(f"Agent session not found: {agent_session_id}") from e
+        if isinstance(e, (ApiError, NotLoggedIn)):
+            raise
+        raise ApiError(f"Agent session runtime access resolve failed: {e}") from e
+
+
 def list_agent_users_can_view(
     agent_id: int | str,
     *,

{mainsequence-3.18.24 → mainsequence-3.19.2}/mainsequence/cli/cli.py

@@ -184,9 +184,11 @@ from .api import (
     remove_team_user_from_view,
     remove_workspace_labels,
     repo_name_from_git_url,
+    resolve_agent_session_runtime_access,
     run_project_job,
     safe_slug,
     schedule_batch_project_jobs,
+    semantic_search_agents,
     start_agent_new_session,
     sync_project_after_commit,
     update_organization_team,
@@ -3569,6 +3571,52 @@ def _agent_detail_impl(
     print_kv("Agent Details", _format_agent_details(agent_payload))
 
 
+def _agent_search_impl(
+    *,
+    q: str,
+    limit: int,
+    timeout: int | None,
+) -> None:
+    _require_login()
+
+    try:
+        results = semantic_search_agents(
+            q,
+            limit=limit,
+            timeout=timeout,
+        )
+    except ApiError as e:
+        error(f"Agent search failed: {e}")
+        raise typer.Exit(1) from e
+
+    if _emit_json(results):
+        return
+
+    rows: list[list[str]] = []
+    for result in results:
+        rows.append(
+            [
+                str(result.get("id") or "-"),
+                str(result.get("agent_unique_id") or "-"),
+                str(result.get("name") or "-"),
+                str(result.get("combined_score") if result.get("combined_score") is not None else "-"),
+                str(result.get("semantic_score") if result.get("semantic_score") is not None else "-"),
+                str(result.get("text_score") if result.get("text_score") is not None else "-"),
+                str(result.get("description") or "-"),
+            ]
+        )
+
+    if rows:
+        print_table(
+            "Agent Search Results",
+            ["ID", "Unique ID", "Name", "Combined", "Semantic", "Text", "Description"],
+            rows,
+        )
+    else:
+        info("No agents matched the search.")
+    info(f'Agent search matches for "{q}": {len(results)}')
+
+
 def _agent_create_impl(
     *,
     name: str | None,
@@ -3812,6 +3860,35 @@ def _agent_session_detail_impl(
     print_kv("Agent Session Details", _format_agent_session_details(agent_session_payload))
 
 
+def _agent_session_resolve_runtime_access_impl(
+    *,
+    agent_session_id: int,
+    timeout: int | None,
+) -> None:
+    _require_login()
+
+    try:
+        runtime_access_payload = resolve_agent_session_runtime_access(agent_session_id, timeout=timeout)
+    except ApiError as e:
+        error(f"Agent session runtime access resolve failed: {e}")
+        raise typer.Exit(1) from e
+
+    if _emit_json(runtime_access_payload):
+        return
+
+    success(f"Agent session runtime access resolved: session_id={agent_session_id}")
+    print_kv(
+        "Agent Session Runtime Access",
+        [
+            ("Coding Agent Service ID", str(runtime_access_payload.get("coding_agent_service_id") or "-")),
+            ("Coding Agent ID", str(runtime_access_payload.get("coding_agent_id") or "-")),
+            ("Mode", str(runtime_access_payload.get("mode") or "-")),
+            ("RPC URL", str(runtime_access_payload.get("rpc_url") or "-")),
+            ("Token", str(runtime_access_payload.get("token") or "-")),
+        ],
+    )
+
+
 def _agent_run_list_impl(
     timeout: int | None,
     filter_entries: list[str] | None,
@@ -5699,6 +5776,31 @@ def agent_detail_cmd(
     _agent_detail_impl(agent_id=agent_id, timeout=timeout)
 
 
+@agent.command("search")
+def agent_search_cmd(
+    q: str = typer.Argument(..., help="Natural-language query to match against agents."),
+    limit: int = typer.Option(20, "--limit", min=1, max=100, help="Maximum number of ranked agent matches to return."),
+    timeout: int | None = typer.Option(None, "--timeout", help="Request timeout in seconds"),
+):
+    """
+    Search agents.
+
+    Uses SDK client `Agent.semantic_search()` as the single source of truth.
+
+    Examples
+    --------
+    ```bash
+    mainsequence agent search "portfolio research copilot"
+    mainsequence agent search "pricing assistant" --limit 10
+    ```
+    """
+    _agent_search_impl(
+        q=q,
+        limit=limit,
+        timeout=timeout,
+    )
+
+
 @agent.command("create")
 def agent_create_cmd(
     name: str | None = pydantic_argument(AGENT_MODEL_REF, "name", None),
@@ -5714,7 +5816,11 @@ def agent_create_cmd(
     labels: list[str] | None = typer.Option(None, "--label", help="Repeatable or comma-separated agent label."),
     llm_provider: str | None = pydantic_option(AGENT_MODEL_REF, "llm_provider", None, "--llm-provider"),
     llm_model: str | None = pydantic_option(AGENT_MODEL_REF, "llm_model", None, "--llm-model"),
-    engine_name: str | None = pydantic_option(AGENT_MODEL_REF, "engine_name", None, "--engine-name"),
+    engine_name: str | None = typer.Option(
+        None,
+        "--engine-name",
+        help="Optional execution engine name to store on the agent.",
+    ),
     runtime_config: str | None = typer.Option(
         None,
         "--runtime-config",
@@ -5766,7 +5872,11 @@ def agent_get_or_create_cmd(
     labels: list[str] | None = typer.Option(None, "--label", help="Repeatable or comma-separated agent label."),
     llm_provider: str | None = pydantic_option(AGENT_MODEL_REF, "llm_provider", None, "--llm-provider"),
     llm_model: str | None = pydantic_option(AGENT_MODEL_REF, "llm_model", None, "--llm-model"),
-    engine_name: str | None = pydantic_option(AGENT_MODEL_REF, "engine_name", None, "--engine-name"),
+    engine_name: str | None = typer.Option(
+        None,
+        "--engine-name",
+        help="Optional execution engine name to store on the agent.",
+    ),
     runtime_config: str | None = typer.Option(
         None,
         "--runtime-config",
@@ -5876,6 +5986,28 @@ def agent_session_detail_cmd(
     _agent_session_detail_impl(agent_session_id=agent_session_id, timeout=timeout)
 
 
+@agent_session_group.command("resolve_runtime_access")
+def agent_session_resolve_runtime_access_cmd(
+    agent_session_id: int = pydantic_argument(
+        AGENT_SESSION_MODEL_REF, "id", ..., help="Agent session ID."
+    ),
+    timeout: int | None = typer.Option(None, "--timeout", help="Request timeout in seconds"),
+):
+    """
+    Resolve runtime access for one agent session.
+
+    Uses SDK client `AgentSession.resolve_runtime_access()` as the single source of truth.
+
+    Examples
+    --------
+    ```bash
+    mainsequence agent session resolve_runtime_access 801
+    mainsequence agent session resolve_runtime_access 801 --timeout 60
+    ```
+    """
+    _agent_session_resolve_runtime_access_impl(agent_session_id=agent_session_id, timeout=timeout)
+
+
 @agent.command("can_view")
 def agent_can_view_cmd(
     agent_id: int = pydantic_argument(AGENT_MODEL_REF, "id", ..., help="Agent ID."),

{mainsequence-3.18.24 → mainsequence-3.19.2}/mainsequence/client/__init__.py

@@ -1,6 +1,5 @@
 from mainsequence.logconf import logger
 
-from .agent import *
 from .command_center import *
 from .models_helpers import *
 from .models_simple_tables import *