asap-protocol 0.3.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

asap/examples/mcp_integration.py

@@ -0,0 +1,240 @@
+"""MCP tool integration example for ASAP protocol.
+
+This module shows how to call MCP (Model Context Protocol) tools via ASAP
+envelopes: build McpToolCall and McpToolResult payloads, wrap them in
+Envelopes, and send/receive using ASAPClient.
+
+Payload types:
+    - mcp_tool_call: Request to invoke an MCP tool (tool_name, arguments).
+    - mcp_tool_result: Response with success/result or error.
+
+Run:
+    uv run python -m asap.examples.mcp_integration
+    uv run python -m asap.examples.mcp_integration --agent-url http://127.0.0.1:8000
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+from typing import Any, Sequence
+
+from asap.models.envelope import Envelope
+from asap.models.ids import generate_id
+from asap.models.payloads import McpToolCall, McpToolResult
+from asap.observability import get_logger
+from asap.transport.client import ASAPClient
+
+logger = get_logger(__name__)
+
+# Default agent that might expose MCP tools (e.g. echo or a custom MCP gateway)
+DEFAULT_AGENT_ID = "urn:asap:agent:mcp-gateway"
+DEFAULT_SENDER_ID = "urn:asap:agent:caller"
+DEFAULT_AGENT_URL = "http://127.0.0.1:8000"
+
+
+def build_mcp_tool_call_envelope(
+    tool_name: str,
+    arguments: dict[str, Any],
+    recipient_id: str = DEFAULT_AGENT_ID,
+    sender_id: str = DEFAULT_SENDER_ID,
+    request_id: str | None = None,
+    mcp_context: dict[str, Any] | None = None,
+) -> Envelope:
+    """Build an ASAP envelope containing an MCP tool call request.
+
+    Args:
+        tool_name: Name of the MCP tool to invoke (e.g. "web_search", "read_file").
+        arguments: JSON-serializable arguments for the tool.
+        recipient_id: URN of the agent that will execute the MCP tool.
+        sender_id: URN of the calling agent.
+        request_id: Optional request ID for correlation; generated if not provided.
+        mcp_context: Optional MCP context (server URL, session, etc.).
+
+    Returns:
+        Envelope with payload_type "mcp_tool_call" and McpToolCall payload.
+    """
+    req_id = request_id or generate_id()
+    payload = McpToolCall(
+        request_id=req_id,
+        tool_name=tool_name,
+        arguments=arguments,
+        mcp_context=mcp_context,
+    )
+    return Envelope(
+        asap_version="0.1",
+        sender=sender_id,
+        recipient=recipient_id,
+        payload_type="mcp_tool_call",
+        payload=payload.model_dump(),
+        trace_id=generate_id(),
+    )
+
+
+def build_mcp_tool_result_envelope(
+    request_id: str,
+    success: bool,
+    result: dict[str, Any] | None = None,
+    error: str | None = None,
+    recipient_id: str = DEFAULT_SENDER_ID,
+    sender_id: str = DEFAULT_AGENT_ID,
+    correlation_id: str | None = None,
+) -> Envelope:
+    """Build an ASAP envelope containing an MCP tool result (response).
+
+    Args:
+        request_id: ID of the original McpToolCall request.
+        success: Whether the tool call succeeded.
+        result: Result data when success=True; must be None when success=False.
+        error: Error message when success=False; must be None when success=True.
+        recipient_id: URN of the agent that sent the tool call (caller).
+        sender_id: URN of the agent that executed the tool (gateway).
+        correlation_id: Envelope ID of the request envelope for tracking.
+
+    Returns:
+        Envelope with payload_type "mcp_tool_result" and McpToolResult payload.
+    """
+    payload = McpToolResult(
+        request_id=request_id,
+        success=success,
+        result=result,
+        error=error,
+    )
+    return Envelope(
+        asap_version="0.1",
+        sender=sender_id,
+        recipient=recipient_id,
+        payload_type="mcp_tool_result",
+        payload=payload.model_dump(),
+        trace_id=generate_id(),
+        correlation_id=correlation_id,
+    )
+
+
+async def send_mcp_tool_call(
+    base_url: str,
+    tool_name: str,
+    arguments: dict[str, Any],
+    sender_id: str = DEFAULT_SENDER_ID,
+    recipient_id: str = DEFAULT_AGENT_ID,
+) -> Envelope:
+    """Send an MCP tool call envelope to an agent and return the response envelope.
+
+    The agent at base_url must handle "mcp_tool_call" and return an envelope
+    with payload_type "mcp_tool_result". If the agent does not implement MCP,
+    the request may fail with a connection or handler error.
+
+    Args:
+        base_url: Base URL of the agent (no trailing /asap).
+        tool_name: MCP tool name to invoke.
+        arguments: Tool arguments.
+        sender_id: Sender URN.
+        recipient_id: Recipient URN.
+
+    Returns:
+        Response envelope (e.g. mcp_tool_result) from the agent.
+    """
+    envelope = build_mcp_tool_call_envelope(
+        tool_name=tool_name,
+        arguments=arguments,
+        recipient_id=recipient_id,
+        sender_id=sender_id,
+    )
+    logger.info(
+        "asap.mcp_integration.sending",
+        tool_name=tool_name,
+        envelope_id=envelope.id,
+    )
+    async with ASAPClient(base_url) as client:
+        response = await client.send(envelope)
+    logger.info(
+        "asap.mcp_integration.received",
+        payload_type=response.payload_type,
+        response_id=response.id,
+    )
+    return response
+
+
+def run_demo_local() -> None:
+    """Demonstrate building MCP envelopes without sending (no server required).
+
+    Builds a tool call envelope and a corresponding tool result envelope
+    to show the expected shape for MCP integration.
+    """
+    request_id = generate_id()
+    call_envelope = build_mcp_tool_call_envelope(
+        tool_name="web_search",
+        arguments={"query": "ASAP protocol", "max_results": 5},
+        request_id=request_id,
+        mcp_context={"server": "mcp://tools.example.com"},
+    )
+    logger.info(
+        "asap.mcp_integration.tool_call_envelope",
+        envelope_id=call_envelope.id,
+        payload_type=call_envelope.payload_type,
+        tool_name=call_envelope.payload.get("tool_name"),
+    )
+
+    result_envelope = build_mcp_tool_result_envelope(
+        request_id=request_id,
+        success=True,
+        result={"findings": ["result1", "result2"], "count": 2},
+        correlation_id=call_envelope.id,
+    )
+    logger.info(
+        "asap.mcp_integration.tool_result_envelope",
+        envelope_id=result_envelope.id,
+        payload_type=result_envelope.payload_type,
+        success=result_envelope.payload.get("success"),
+    )
+
+
+async def run_demo_remote(agent_url: str) -> None:
+    """Send a real MCP tool call to an agent (agent must support mcp_tool_call).
+
+    If the agent does not register a handler for mcp_tool_call, the request
+    will fail; this demo is for use with an MCP-capable agent.
+    """
+    try:
+        response = await send_mcp_tool_call(
+            base_url=agent_url,
+            tool_name="echo",
+            arguments={"message": "hello from MCP example"},
+        )
+        logger.info(
+            "asap.mcp_integration.remote_complete",
+            payload_type=response.payload_type,
+            payload=response.payload,
+        )
+    except Exception as e:
+        logger.warning(
+            "asap.mcp_integration.remote_failed",
+            error=str(e),
+            message="Ensure the agent supports mcp_tool_call or run without --agent-url",
+        )
+        raise
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    """Parse command-line arguments for the MCP integration demo."""
+    parser = argparse.ArgumentParser(
+        description="Call MCP tools via ASAP envelopes (build and optionally send)."
+    )
+    parser.add_argument(
+        "--agent-url",
+        default=None,
+        help="Base URL of an agent that handles mcp_tool_call (optional; if omitted, only build envelopes).",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Build MCP envelopes and optionally send to an agent."""
+    args = parse_args(argv)
+    run_demo_local()
+    if args.agent_url:
+        asyncio.run(run_demo_remote(args.agent_url))
+
+
+if __name__ == "__main__":
+    main()

asap/examples/multi_step_workflow.py

@@ -0,0 +1,134 @@
+"""Multi-step workflow example for ASAP protocol.
+
+This module demonstrates a pipeline of steps (fetch -> transform -> summarize)
+where each step consumes input and produces output; state flows between steps.
+Use this pattern for workflows that could be split across agents (each step
+as a TaskRequest to a different agent) or run in-process.
+
+Use case: Multi-agent pipelines, ETL-style workflows, or sequential task chains.
+
+Run:
+    uv run python -m asap.examples.multi_step_workflow
+"""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from typing import Any, Callable, Sequence
+
+from asap.models.ids import generate_id
+from asap.observability import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class WorkflowState:
+    """State passed between workflow steps.
+
+    In a distributed setup, this could be a TaskRequest input or
+    TaskResponse result; here we keep it simple for the example.
+    """
+
+    step_name: str
+    data: dict[str, Any]
+    task_id: str | None = None
+
+
+def make_step(
+    name: str, fn: Callable[[dict[str, Any]], dict[str, Any]]
+) -> Callable[[WorkflowState], WorkflowState]:
+    """Wrap a function as a workflow step that takes and returns WorkflowState.
+
+    Args:
+        name: Step name for logging and state.
+        fn: Function that takes input dict and returns output dict.
+
+    Returns:
+        Callable(WorkflowState) -> WorkflowState.
+    """
+
+    def step(state: WorkflowState) -> WorkflowState:
+        out = fn(state.data)
+        logger.info(
+            "asap.multi_step_workflow.step",
+            step_name=name,
+            input_keys=list(state.data.keys()),
+            output_keys=list(out.keys()),
+        )
+        return WorkflowState(step_name=name, data=out, task_id=state.task_id)
+
+    return step
+
+
+def run_workflow(
+    initial_data: dict[str, Any],
+    steps: Sequence[Callable[[WorkflowState], WorkflowState]],
+    task_id: str | None = None,
+) -> WorkflowState:
+    """Run a linear workflow: initial_data -> step1 -> step2 -> ... -> final state.
+
+    Args:
+        initial_data: Input for the first step.
+        steps: List of step functions (each takes WorkflowState, returns WorkflowState).
+        task_id: Optional task ID for correlation.
+
+    Returns:
+        Final WorkflowState after all steps.
+    """
+    task_id = task_id or generate_id()
+    state = WorkflowState(step_name="init", data=initial_data, task_id=task_id)
+    for step in steps:
+        state = step(state)
+    logger.info(
+        "asap.multi_step_workflow.complete",
+        task_id=task_id,
+        final_step=state.step_name,
+    )
+    return state
+
+
+def run_demo() -> WorkflowState:
+    """Run a demo workflow: fetch -> transform -> summarize."""
+
+    def fetch(data: dict[str, Any]) -> dict[str, Any]:
+        return {"raw": ["item1", "item2", "item3"], "count": 3}
+
+    def transform(data: dict[str, Any]) -> dict[str, Any]:
+        raw = data.get("raw", [])
+        return {"transformed": [x.upper() for x in raw], "count": len(raw)}
+
+    def summarize(data: dict[str, Any]) -> dict[str, Any]:
+        transformed = data.get("transformed", [])
+        return {"summary": f"Processed {len(transformed)} items", "items": transformed}
+
+    steps = [
+        make_step("fetch", fetch),
+        make_step("transform", transform),
+        make_step("summarize", summarize),
+    ]
+    return run_workflow(initial_data={}, steps=steps)
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    """Parse command-line arguments for the workflow demo."""
+    parser = argparse.ArgumentParser(
+        description="Multi-step workflow example (fetch -> transform -> summarize)."
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Run the multi-step workflow demo."""
+    parse_args(argv)
+    final = run_demo()
+    logger.info(
+        "asap.multi_step_workflow.demo_complete",
+        final_data_keys=list(final.data.keys()),
+        summary=final.data.get("summary"),
+    )
+
+
+if __name__ == "__main__":
+    main()

asap/examples/orchestration.py

@@ -0,0 +1,293 @@
+"""Multi-agent orchestration example for ASAP protocol.
+
+This module demonstrates a main (orchestrator) agent delegating work to two
+sub-agents, with explicit task coordination and state tracking. Use it as
+a reference for building multi-agent workflows (3+ agents).
+
+Scenario:
+    - Orchestrator receives a high-level task, splits it into two sub-tasks.
+    - Sub-agent A and Sub-agent B each handle one sub-task (e.g. "fetch" and "summarize").
+    - Orchestrator coordinates order, collects results, and tracks state.
+
+Run:
+    Start two echo agents (or your own agents) on ports 8001 and 8002, then:
+    uv run python -m asap.examples.orchestration --worker-a-url http://127.0.0.1:8001 --worker-b-url http://127.0.0.1:8002
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any, Sequence
+
+from asap.models.entities import Capability, Endpoint, Manifest, Skill
+from asap.models.envelope import Envelope
+from asap.models.ids import generate_id
+from asap.models.payloads import TaskRequest
+from asap.observability import get_logger
+from asap.observability.logging import bind_context, clear_context
+from asap.transport.client import ASAPClient
+
+logger = get_logger(__name__)
+
+# Orchestrator (main agent)
+ORCHESTRATOR_ID = "urn:asap:agent:orchestrator"
+ORCHESTRATOR_NAME = "Orchestrator Agent"
+ORCHESTRATOR_VERSION = "0.1.0"
+ORCHESTRATOR_DESCRIPTION = "Coordinates tasks across two sub-agents"
+
+# Sub-agents (default: two echo agents on different ports)
+SUB_AGENT_A_ID = "urn:asap:agent:worker-a"
+SUB_AGENT_B_ID = "urn:asap:agent:worker-b"
+DEFAULT_WORKER_A_URL = "http://127.0.0.1:8001"
+DEFAULT_WORKER_B_URL = "http://127.0.0.1:8002"
+
+
+@dataclass
+class OrchestrationState:
+    """Tracks progress and results across the orchestration workflow.
+
+    Used for task coordination and observability: which step we are in,
+    what each sub-agent returned, and final status.
+    """
+
+    conversation_id: str
+    trace_id: str
+    step: str = "init"
+    result_a: dict[str, Any] | None = None
+    result_b: dict[str, Any] | None = None
+    error: str | None = None
+    completed: bool = False
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize state for logging or persistence."""
+        return {
+            "conversation_id": self.conversation_id,
+            "trace_id": self.trace_id,
+            "step": self.step,
+            "result_a": self.result_a,
+            "result_b": self.result_b,
+            "error": self.error,
+            "completed": self.completed,
+            "metadata": self.metadata,
+        }
+
+
+def build_orchestrator_manifest(asap_endpoint: str = "http://localhost:8000/asap") -> Manifest:
+    """Build the manifest for the orchestrator agent.
+
+    Args:
+        asap_endpoint: URL where the orchestrator receives ASAP messages.
+
+    Returns:
+        Manifest describing the orchestrator's capabilities and endpoints.
+    """
+    return Manifest(
+        id=ORCHESTRATOR_ID,
+        name=ORCHESTRATOR_NAME,
+        version=ORCHESTRATOR_VERSION,
+        description=ORCHESTRATOR_DESCRIPTION,
+        capabilities=Capability(
+            asap_version="0.1",
+            skills=[
+                Skill(
+                    id="orchestrate", description="Delegate and coordinate work across sub-agents"
+                ),
+            ],
+            state_persistence=False,
+        ),
+        endpoints=Endpoint(asap=asap_endpoint),
+    )
+
+
+def build_task_envelope(
+    recipient_id: str,
+    skill_id: str,
+    input_payload: dict[str, Any],
+    conversation_id: str,
+    trace_id: str,
+    parent_task_id: str | None = None,
+) -> Envelope:
+    """Build a TaskRequest envelope for a sub-agent.
+
+    Args:
+        recipient_id: URN of the sub-agent.
+        skill_id: Skill to invoke (e.g. "echo" for echo agents).
+        input_payload: Input dict for the skill.
+        conversation_id: Shared conversation ID for the workflow.
+        trace_id: Shared trace ID for distributed tracing.
+        parent_task_id: Optional parent task ID for hierarchy.
+
+    Returns:
+        Envelope ready to send via ASAPClient.
+    """
+    task_request = TaskRequest(
+        conversation_id=conversation_id,
+        parent_task_id=parent_task_id,
+        skill_id=skill_id,
+        input=input_payload,
+    )
+    return Envelope(
+        asap_version="0.1",
+        sender=ORCHESTRATOR_ID,
+        recipient=recipient_id,
+        payload_type="task.request",
+        payload=task_request.model_dump(),
+        trace_id=trace_id,
+    )
+
+
+async def send_to_sub_agent(
+    client: ASAPClient,
+    envelope: Envelope,
+) -> Envelope:
+    """Send an envelope to a sub-agent and return the response envelope.
+
+    Uses the provided client so the caller can reuse a single ASAPClient
+    instance for multiple requests (e.g. one client per worker in run_orchestration).
+
+    Args:
+        client: Open ASAPClient connected to the sub-agent (caller owns lifecycle).
+        envelope: TaskRequest envelope to send.
+
+    Returns:
+        Response envelope from the sub-agent (e.g. TaskResponse).
+    """
+    return await client.send(envelope)
+
+
+async def run_orchestration(
+    worker_a_url: str = DEFAULT_WORKER_A_URL,
+    worker_b_url: str = DEFAULT_WORKER_B_URL,
+    input_a: dict[str, Any] | None = None,
+    input_b: dict[str, Any] | None = None,
+) -> OrchestrationState:
+    """Run the orchestration: delegate to sub-agent A, then sub-agent B, and track state.
+
+    Task coordination: steps run sequentially (A then B). State is updated after
+    each response so you can inspect or persist progress.
+
+    Args:
+        worker_a_url: Base URL for sub-agent A.
+        worker_b_url: Base URL for sub-agent B.
+        input_a: Input payload for sub-agent A (default: step "a" message).
+        input_b: Input payload for sub-agent B (default: step "b" message).
+
+    Returns:
+        Final orchestration state with both results and completion status.
+    """
+    conversation_id = generate_id()
+    trace_id = generate_id()
+    state = OrchestrationState(conversation_id=conversation_id, trace_id=trace_id)
+    state.step = "start"
+    state.metadata["worker_a_url"] = worker_a_url
+    state.metadata["worker_b_url"] = worker_b_url
+
+    payload_a = input_a if input_a is not None else {"step": "a", "message": "task for worker A"}
+    payload_b = input_b if input_b is not None else {"step": "b", "message": "task for worker B"}
+
+    bind_context(trace_id=trace_id, correlation_id=conversation_id)
+    try:
+        async with ASAPClient(worker_a_url) as client_a, ASAPClient(worker_b_url) as client_b:
+            state.step = "sent_to_a"
+            envelope_a = build_task_envelope(
+                recipient_id=SUB_AGENT_A_ID,
+                skill_id="echo",
+                input_payload=payload_a,
+                conversation_id=conversation_id,
+                trace_id=trace_id,
+            )
+            logger.info(
+                "asap.orchestration.sent_to_a",
+                envelope_id=envelope_a.id,
+                recipient=SUB_AGENT_A_ID,
+            )
+            try:
+                response_a = await send_to_sub_agent(client_a, envelope_a)
+                state.result_a = response_a.payload
+                state.step = "received_from_a"
+            except Exception as e:  # noqa: BLE001
+                state.error = f"worker_a: {e!s}"
+                state.step = "failed_at_a"
+                clear_context()
+                return state
+
+            state.step = "sent_to_b"
+            envelope_b = build_task_envelope(
+                recipient_id=SUB_AGENT_B_ID,
+                skill_id="echo",
+                input_payload=payload_b,
+                conversation_id=conversation_id,
+                trace_id=trace_id,
+            )
+            logger.info(
+                "asap.orchestration.sent_to_b",
+                envelope_id=envelope_b.id,
+                recipient=SUB_AGENT_B_ID,
+            )
+            try:
+                response_b = await send_to_sub_agent(client_b, envelope_b)
+                state.result_b = response_b.payload
+                state.step = "received_from_b"
+            except Exception as e:  # noqa: BLE001
+                state.error = f"worker_b: {e!s}"
+                state.step = "failed_at_b"
+                clear_context()
+                return state
+
+        state.step = "completed"
+        state.completed = True
+        logger.info(
+            "asap.orchestration.complete",
+            conversation_id=conversation_id,
+            state=state.to_dict(),
+        )
+    finally:
+        clear_context()
+
+    return state
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    """Parse command-line arguments for the orchestration demo.
+
+    Args:
+        argv: Optional list of CLI arguments for testing.
+
+    Returns:
+        Parsed argparse namespace.
+    """
+    parser = argparse.ArgumentParser(
+        description="Run multi-agent orchestration (orchestrator + 2 sub-agents)."
+    )
+    parser.add_argument(
+        "--worker-a-url",
+        default=DEFAULT_WORKER_A_URL,
+        help="Base URL for sub-agent A (e.g. echo agent on 8001).",
+    )
+    parser.add_argument(
+        "--worker-b-url",
+        default=DEFAULT_WORKER_B_URL,
+        help="Base URL for sub-agent B (e.g. echo agent on 8002).",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Run a single orchestration round: delegate to worker A then B and print state."""
+    args = parse_args(argv)
+    state = asyncio.run(
+        run_orchestration(
+            worker_a_url=args.worker_a_url,
+            worker_b_url=args.worker_b_url,
+        )
+    )
+    logger.info("asap.orchestration.demo_complete", state=state.to_dict())
+    if state.error:
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()