Skip to content
Core ConceptsCLI ReferenceAPI Reference
AGH RuntimeAPI Reference

Network

AGH Network HTTP endpoints.

Audience
Operators running durable agent work
Focus
API Reference guidance shaped for scanability, day-two clarity, and operator context.

List materialized network channels

GET/api/network/channels

Response Body

application/json

application/json

application/json

curl -X GET "https://loading/api/network/channels"
{
  "channels": [
    {
      "channel": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": "string",
      "historical_participant_count": 0,
      "last_activity_at": "2019-08-24T14:15:22Z",
      "last_message_preview": "string",
      "last_presence_at": "2019-08-24T14:15:22Z",
      "local_peer_count": 0,
      "message_count": 0,
      "peer_count": 0,
      "presence_count": 0,
      "purpose": "string",
      "remote_peer_count": 0,
      "session_count": 0,
      "workspace_id": "string"
    }
  ]
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Create a network channel by spawning agent sessions

POST/api/network/channels

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/network/channels" \  -H "Content-Type: application/json" \  -d '{    "agent_names": [      "string"    ],    "channel": "string",    "purpose": "string",    "workspace_id": "string"  }'
{
  "channel": {
    "channel": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": "string",
    "historical_participant_count": 0,
    "kind_counts": [
      {
        "count": 0,
        "kind": "string"
      }
    ],
    "last_activity_at": "2019-08-24T14:15:22Z",
    "last_message_preview": "string",
    "last_presence_at": "2019-08-24T14:15:22Z",
    "local_peer_count": 0,
    "message_count": 0,
    "peer_count": 0,
    "peers": [
      {
        "channel": "string",
        "display_name": "string",
        "expires_at": "2019-08-24T14:15:22Z",
        "joined_at": "2019-08-24T14:15:22Z",
        "last_seen": "2019-08-24T14:15:22Z",
        "local": true,
        "peer_card": {
          "artifacts_supported": [
            "string"
          ],
          "capabilities": [
            {
              "id": "string",
              "summary": "string"
            }
          ],
          "display_name": "string",
          "ext": {
            "property1": null,
            "property2": null
          },
          "peer_id": "string",
          "profiles_supported": [
            "string"
          ],
          "trust_modes_supported": [
            "string"
          ]
        },
        "peer_id": "string",
        "session_id": "string"
      }
    ],
    "presence_count": 0,
    "purpose": "string",
    "remote_peer_count": 0,
    "session_count": 0,
    "sessions": [
      {
        "acp_caps": {
          "supported_models": [
            "string"
          ],
          "supported_modes": [
            "string"
          ],
          "supports_load_session": true
        },
        "acp_session_id": "string",
        "activity": {
          "current_tool": "string",
          "elapsed_seconds": 0,
          "idle_seconds": 0,
          "iteration_current": 0,
          "iteration_max": 0,
          "last_activity_at": "2019-08-24T14:15:22Z",
          "last_activity_detail": "string",
          "last_activity_kind": "string",
          "last_progress_at": "2019-08-24T14:15:22Z",
          "tool_call_id": "string",
          "turn_id": "string",
          "turn_source": "string",
          "turn_started_at": "2019-08-24T14:15:22Z"
        },
        "agent_name": "string",
        "channel": "string",
        "created_at": "2019-08-24T14:15:22Z",
        "failure": {
          "crash_bundle_path": "string",
          "kind": "string",
          "summary": "string"
        },
        "health": {
          "active_prompt": true,
          "agent_name": "string",
          "attachable": true,
          "eligible_for_wake": true,
          "health": "healthy",
          "ineligibility_reason": "session_prompt_active",
          "last_activity_at": "2019-08-24T14:15:22Z",
          "last_error": "string",
          "last_presence_at": "2019-08-24T14:15:22Z",
          "session_id": "string",
          "state": "idle",
          "updated_at": "2019-08-24T14:15:22Z",
          "workspace_id": "string"
        },
        "id": "string",
        "lineage": {
          "auto_stop_on_parent": true,
          "parent_session_id": "string",
          "permission_policy": {
            "mcp_servers": [
              "string"
            ],
            "network_channels": [
              "string"
            ],
            "sandbox_profiles": [
              "string"
            ],
            "skills": [
              "string"
            ],
            "tools": [
              "string"
            ],
            "workspace_paths": [
              "string"
            ]
          },
          "root_session_id": "string",
          "spawn_budget": {
            "max_active_per_workspace": 0,
            "max_children": 0,
            "max_depth": 0,
            "ttl_seconds": 0
          },
          "spawn_depth": 0,
          "spawn_role": "string",
          "ttl_expires_at": "2019-08-24T14:15:22Z"
        },
        "name": "string",
        "provider": "string",
        "sandbox": {
          "backend": "string",
          "instance_id": "string",
          "last_sync_error": "string",
          "profile": "string",
          "provider_state_json": null,
          "sandbox_id": "string",
          "state": "string"
        },
        "state": "starting",
        "stop_detail": "string",
        "stop_reason": "completed",
        "type": "string",
        "updated_at": "2019-08-24T14:15:22Z",
        "workspace_id": "string",
        "workspace_path": "string"
      }
    ],
    "workspace_id": "string"
  }
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Get one network channel detail

GET/api/network/channels/{channel}

Path Parameters

channel*string

Network channel

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://loading/api/network/channels/string"
{
  "channel": {
    "channel": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "created_by": "string",
    "historical_participant_count": 0,
    "kind_counts": [
      {
        "count": 0,
        "kind": "string"
      }
    ],
    "last_activity_at": "2019-08-24T14:15:22Z",
    "last_message_preview": "string",
    "last_presence_at": "2019-08-24T14:15:22Z",
    "local_peer_count": 0,
    "message_count": 0,
    "peer_count": 0,
    "peers": [
      {
        "channel": "string",
        "display_name": "string",
        "expires_at": "2019-08-24T14:15:22Z",
        "joined_at": "2019-08-24T14:15:22Z",
        "last_seen": "2019-08-24T14:15:22Z",
        "local": true,
        "peer_card": {
          "artifacts_supported": [
            "string"
          ],
          "capabilities": [
            {
              "id": "string",
              "summary": "string"
            }
          ],
          "display_name": "string",
          "ext": {
            "property1": null,
            "property2": null
          },
          "peer_id": "string",
          "profiles_supported": [
            "string"
          ],
          "trust_modes_supported": [
            "string"
          ]
        },
        "peer_id": "string",
        "session_id": "string"
      }
    ],
    "presence_count": 0,
    "purpose": "string",
    "remote_peer_count": 0,
    "session_count": 0,
    "sessions": [
      {
        "acp_caps": {
          "supported_models": [
            "string"
          ],
          "supported_modes": [
            "string"
          ],
          "supports_load_session": true
        },
        "acp_session_id": "string",
        "activity": {
          "current_tool": "string",
          "elapsed_seconds": 0,
          "idle_seconds": 0,
          "iteration_current": 0,
          "iteration_max": 0,
          "last_activity_at": "2019-08-24T14:15:22Z",
          "last_activity_detail": "string",
          "last_activity_kind": "string",
          "last_progress_at": "2019-08-24T14:15:22Z",
          "tool_call_id": "string",
          "turn_id": "string",
          "turn_source": "string",
          "turn_started_at": "2019-08-24T14:15:22Z"
        },
        "agent_name": "string",
        "channel": "string",
        "created_at": "2019-08-24T14:15:22Z",
        "failure": {
          "crash_bundle_path": "string",
          "kind": "string",
          "summary": "string"
        },
        "health": {
          "active_prompt": true,
          "agent_name": "string",
          "attachable": true,
          "eligible_for_wake": true,
          "health": "healthy",
          "ineligibility_reason": "session_prompt_active",
          "last_activity_at": "2019-08-24T14:15:22Z",
          "last_error": "string",
          "last_presence_at": "2019-08-24T14:15:22Z",
          "session_id": "string",
          "state": "idle",
          "updated_at": "2019-08-24T14:15:22Z",
          "workspace_id": "string"
        },
        "id": "string",
        "lineage": {
          "auto_stop_on_parent": true,
          "parent_session_id": "string",
          "permission_policy": {
            "mcp_servers": [
              "string"
            ],
            "network_channels": [
              "string"
            ],
            "sandbox_profiles": [
              "string"
            ],
            "skills": [
              "string"
            ],
            "tools": [
              "string"
            ],
            "workspace_paths": [
              "string"
            ]
          },
          "root_session_id": "string",
          "spawn_budget": {
            "max_active_per_workspace": 0,
            "max_children": 0,
            "max_depth": 0,
            "ttl_seconds": 0
          },
          "spawn_depth": 0,
          "spawn_role": "string",
          "ttl_expires_at": "2019-08-24T14:15:22Z"
        },
        "name": "string",
        "provider": "string",
        "sandbox": {
          "backend": "string",
          "instance_id": "string",
          "last_sync_error": "string",
          "profile": "string",
          "provider_state_json": null,
          "sandbox_id": "string",
          "state": "string"
        },
        "state": "starting",
        "stop_detail": "string",
        "stop_reason": "completed",
        "type": "string",
        "updated_at": "2019-08-24T14:15:22Z",
        "workspace_id": "string",
        "workspace_path": "string"
      }
    ],
    "workspace_id": "string"
  }
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

List the read-only timeline for one network channel

GET/api/network/channels/{channel}/messages

Path Parameters

channel*string

Network channel

Query Parameters

before?string

Return messages before the specified message id

after?string

Return messages after the specified message id

include_presence?boolean

Include coalesced presence episodes in the timeline

limit?integer

Maximum number of timeline messages to return

Formatint32

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://loading/api/network/channels/string/messages"
{
  "messages": [
    {
      "body": null,
      "causation_id": "string",
      "channel": "string",
      "direction": "string",
      "display_name": "string",
      "intent": "string",
      "interaction_id": "string",
      "kind": "string",
      "local": true,
      "message_id": "string",
      "peer_from": "string",
      "peer_to": "string",
      "presence_count": 0,
      "presence_last_seen_at": "2019-08-24T14:15:22Z",
      "presence_started_at": "2019-08-24T14:15:22Z",
      "preview_text": "string",
      "reply_to": "string",
      "session_id": "string",
      "text": "string",
      "timestamp": "2019-08-24T14:15:22Z",
      "trace_id": "string"
    }
  ]
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

List queued network inbox messages for one local session

GET/api/network/inbox

Query Parameters

session_id*string

Target local session id

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://loading/api/network/inbox?session_id=string"
{
  "messages": [
    {
      "body": null,
      "causation_id": "string",
      "channel": "string",
      "expires_at": 0,
      "ext": {
        "property1": null,
        "property2": null
      },
      "from": "string",
      "id": "string",
      "interaction_id": "string",
      "kind": "string",
      "proof": {
        "property1": null,
        "property2": null
      },
      "protocol": "string",
      "reply_to": "string",
      "to": "string",
      "trace_id": "string",
      "ts": 0
    }
  ]
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

List visible network peers

GET/api/network/peers

Query Parameters

channel?string

Filter peers by channel

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://loading/api/network/peers"
{
  "peers": [
    {
      "channel": "string",
      "display_name": "string",
      "expires_at": "2019-08-24T14:15:22Z",
      "joined_at": "2019-08-24T14:15:22Z",
      "last_seen": "2019-08-24T14:15:22Z",
      "local": true,
      "peer_card": {
        "artifacts_supported": [
          "string"
        ],
        "capabilities": [
          {
            "id": "string",
            "summary": "string"
          }
        ],
        "display_name": "string",
        "ext": {
          "property1": null,
          "property2": null
        },
        "peer_id": "string",
        "profiles_supported": [
          "string"
        ],
        "trust_modes_supported": [
          "string"
        ]
      },
      "peer_id": "string",
      "session_id": "string"
    }
  ]
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Get one visible network peer detail

GET/api/network/peers/{peer_id}

Path Parameters

peer_id*string

Network peer id

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://loading/api/network/peers/string"
{
  "peer": {
    "capability_catalog": {
      "capabilities": [
        {
          "artifacts_expected": [
            "string"
          ],
          "constraints": [
            "string"
          ],
          "context_needed": [
            "string"
          ],
          "digest": "string",
          "examples": [
            "string"
          ],
          "execution_outline": [
            "string"
          ],
          "id": "string",
          "outcome": "string",
          "requirements": [
            "string"
          ],
          "summary": "string",
          "version": "string"
        }
      ]
    },
    "channel": "string",
    "display_name": "string",
    "expires_at": "2019-08-24T14:15:22Z",
    "joined_at": "2019-08-24T14:15:22Z",
    "last_seen": "2019-08-24T14:15:22Z",
    "local": true,
    "metrics": {
      "delivered": 0,
      "received": 0,
      "rejected": 0,
      "sent": 0
    },
    "peer_card": {
      "artifacts_supported": [
        "string"
      ],
      "capabilities": [
        {
          "id": "string",
          "summary": "string"
        }
      ],
      "display_name": "string",
      "ext": {
        "property1": null,
        "property2": null
      },
      "peer_id": "string",
      "profiles_supported": [
        "string"
      ],
      "trust_modes_supported": [
        "string"
      ]
    },
    "peer_id": "string",
    "session_id": "string"
  }
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

List the directed room timeline for one network peer

GET/api/network/peers/{peer_id}/messages

Path Parameters

peer_id*string

Network peer id

Query Parameters

before?string

Return messages before the specified message id

after?string

Return messages after the specified message id

include_presence?boolean

Include coalesced presence episodes in the timeline

limit?integer

Maximum number of timeline messages to return

Formatint32

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://loading/api/network/peers/string/messages"
{
  "messages": [
    {
      "body": null,
      "causation_id": "string",
      "channel": "string",
      "direction": "string",
      "display_name": "string",
      "intent": "string",
      "interaction_id": "string",
      "kind": "string",
      "local": true,
      "message_id": "string",
      "peer_from": "string",
      "peer_to": "string",
      "presence_count": 0,
      "presence_last_seen_at": "2019-08-24T14:15:22Z",
      "presence_started_at": "2019-08-24T14:15:22Z",
      "preview_text": "string",
      "reply_to": "string",
      "session_id": "string",
      "text": "string",
      "timestamp": "2019-08-24T14:15:22Z",
      "trace_id": "string"
    }
  ]
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Send one network message

POST/api/network/send

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/network/send" \  -H "Content-Type: application/json" \  -d '{    "body": null,    "channel": "string",    "kind": "string",    "session_id": "string"  }'
{
  "message": {
    "causation_id": "string",
    "channel": "string",
    "expires_at": 0,
    "ext": {
      "property1": null,
      "property2": null
    },
    "id": "string",
    "interaction_id": "string",
    "kind": "string",
    "reply_to": "string",
    "session_id": "string",
    "to": "string",
    "trace_id": "string"
  }
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
{
  "error": "string"
}
Empty

Get the network runtime status snapshot

GET/api/network/status

Response Body

application/json

application/json

curl -X GET "https://loading/api/network/status"
{
  "network": {
    "channels": 0,
    "configured_default_channel": "string",
    "declared_channels": [
      {
        "activation_id": "string",
        "bundle_name": "string",
        "description": "string",
        "extension_name": "string",
        "name": "string",
        "primary": true,
        "profile_name": "string",
        "workspace_id": "string"
      }
    ],
    "delivery_workers": 0,
    "effective_default_channel": "string",
    "effective_default_source": "string",
    "enabled": true,
    "handoff_tagged_events": 0,
    "kind_metrics": [
      {
        "delivered": 0,
        "kind": "string",
        "received": 0,
        "rejected": 0,
        "sent": 0
      }
    ],
    "last_disconnect": "string",
    "listener_host": "string",
    "listener_port": 0,
    "local_peers": 0,
    "messages_delivered": 0,
    "messages_received": 0,
    "messages_rejected": 0,
    "messages_sent": 0,
    "queued_messages": 0,
    "queued_sessions": 0,
    "remote_peers": 0,
    "status": "string",
    "workflow_tagged_events": 0
  }
}
{
  "error": "string"
}
Empty

Bridges

AGH Bridges HTTP endpoints.

Observe

AGH Observe HTTP endpoints.