Agent Workflows

Agent Workflows & Orchestration

Overview

This skill consolidates tools and methodologies for managing agents, dispatching subagents, and direct Agent-to-Agent (A2A) communication via JSON-RPC.

Capabilities/Tools

1. Agent Manager CLI (scripts/main.py)

This script enables controlling other independent agents running in the ecosystem. It manages runtimes, heartbeats, states, and lifecycles.

# List all running agents
python scripts/main.py list

# Start an agent heartbeat
python scripts/main.py heartbeat start <agent_name>

# Check the status of agent runtimes
python scripts/main.py status

# Schedule a task to run periodically
python scripts/main.py schedule <agent_name> "cron_expression"

2. A2A Client (scripts/a2a_client.py)

This tool allows the agent to act as a client and communicate with other A2A-compatible agents. It handles agent discovery (agent-card.json), message sending (JSON-RPC), task queue monitoring, and result polling or streaming (SSE).

Usage: Run the script with the target agent's explicitly provided URL or the target agent's Name (from AGENTS.md), along with your query and the desired action.

Available Actions:

• chat (default): Send a message and wait for the result.
• get-card: Retrieve and display the agent's full capability card.
• list-tasks: Monitor the agent's active task queue.

Examples:

# 1. Ask an agent to search the web (polling)
python scripts/a2a_client.py \
  --agent-name SearchMaster \
  --action chat \
  --query "Can you search the latest news about the United States?"

# 2. Ask an agent and stream real-time updates (SSE)
python scripts/a2a_client.py \
  --url https://agent.example.test/a2a/ \
  --action chat \
  --stream \
  --query "Explain quantum mechanics in 1 line."

# 3. View the Agent Card capabilities
python scripts/a2a_client.py --agent-name SearchMaster --action get-card

# 4. Monitor the Agent's Task Queue
python scripts/a2a_client.py --url https://agent.example.test/a2a/ --action list-tasks

# For private endpoints, resolve the URL and verified CA profile through AgentConfig.

A2A JSON-RPC Endpoint Reference

All requests are sent as POST to the agent's A2A base URL with Content-Type: application/json. The id, jsonrpc: "2.0", and method fields are always required in the request envelope.

Agent Discovery (HTTP GET — not JSON-RPC)

Message Operations

message/send payload shape:

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": "<uuid>",
  "params": {
    "message": {
      "kind": "message",
      "role": "user",
      "parts": [{ "kind": "text", "text": "<your query>" }],
      "messageId": "<uuid>"
    },
    "configuration": { }
  }
}

message/stream payload shape — same as message/send but set Accept: text/event-stream. The server responds with SSE lines (data: {...}), ending with [DONE].

Task Operations

tasks/get payload shape:

{
  "jsonrpc": "2.0",
  "method": "tasks/get",
  "id": "<uuid>",
  "params": { "id": "<task_id>" }
}

tasks/cancel payload shape:

{
  "jsonrpc": "2.0",
  "method": "tasks/cancel",
  "id": "<uuid>",
  "params": { "id": "<task_id>" }
}

tasks/resubscribe payload shape — sends TaskIdParams ({ "id": "<task_id>" }), set Accept: text/event-stream.

Push Notification Operations

[!NOTE] Push notification endpoints are optional. Agents that do not support them will return PushNotificationNotSupportedError (-32003).

tasks/pushNotification/set payload shape:

{
  "jsonrpc": "2.0",
  "method": "tasks/pushNotification/set",
  "id": "<uuid>",
  "params": {
    "taskId": "<task_id>",
    "pushNotificationConfig": {
      "url": "https://my-receiver.example.com/webhook",
      "token": "<optional_auth_token>"
    }
  }
}

JSON-RPC Error Code Reference

Response Envelope

All non-streaming responses follow this JSON-RPC 2.0 envelope:

{
  "jsonrpc": "2.0",
  "id": "<echoed_request_id>",
  "result": { ... },
  "error": { "code": -32001, "message": "Task not found", "data": null }
}

Only one of result or error will be present. Always check for "error" before reading "result".

Workflows

3. A2A & Subagent Methodologies (docs/)

Follow the patterns outlined in the docs/ folder when designing workflows that involve spawning independent agent worker nodes:

• A2A Orchestration: Use explicit protocol interfaces when communicating between isolated AI agents. Ensure one agent serves as the coordinator while others act as execution workers.
• Dispatching Parallel Agents: Don't force one agent to do multiple isolated tasks sequentially. Spin up multiple isolated environments (or TMUX sessions) and invoke worker routines in parallel for faster results.
• Subagent-Driven Development: During complex execution tasks, break down the work into discrete chunks and farm it out to specialized subagents. You are the supervisor; they are the workers. Ensure they have clear constraints and output expected artifacts that you can subsequently review.