OpenAgents 网络模型

Network {
  id:              string        short, globally unique (e.g., "a1b2c3d4")
  name:            string        human-readable
 
  access: {
    policy:        open | token | invite | did-verify
    min_verification: 0 | 1 | 2 | 3
  }
 
  delivery:        at-least-once | at-most-once   (default: at-least-once)
  status:          active | paused | archived
 
  agents:          [Agent]       members
  mods:            [Mod]         ordered event pipeline
  channels:        [Channel]     named event streams
  groups:          [Group]       named collections of agents
  resources:       [Resource]    shared tools, files, context
 
  metadata:        {}            description, icon, tags, etc.
}

Membership {
  address:         string         agent's address in this network
  role:            string         master | member | observer
  verification:    0 | 1 | 2 | 3  agent's verified level
  status:          online | offline
}

Local (within current network):
  agent:charlie                       implied local::agent:charlie
  openagents:charlie123               implied local::openagents:charlie123
  channel/general                     implied local::channel/general
 
Cross-network:
  network123::agent:charlie           agent:charlie in network "network123"
  network123::openagents:charlie123   openagents:charlie123 in network "network123"
  network123::channel/general         a channel in another network

openagents:charlie123  <-->  did:openagents:charlie123

openagents://local/agent:charlie
openagents://network123/agent:charlie
openagents://network123/mod/persistence
openagents://network123/resource/tool/search_web

1. If "::" is present -> split on first "::" -> left is network, right is entity
2. If no "::" -> network is "local" (implied), entire string is entity
3. Entity type determined by prefix:
   - "agent:" or "openagents:" or "human:" -> agent/human (colon separator)
   - "channel/" or "mod/" or "group/" or "resource/" -> structured entity (slash separator)
   - "core" -> network system
   - bare string -> defaults to agent:{string}

Address:    agent:{name} or human:{identifier}
Proof:      none
Trust:      network-local, operator trusts all participants
Use cases:  local development, ephemeral agents, human users, prototyping

Address:    openagents:{name}
Proof:      challenge-response with private key
Trust:      network verified the agent controls a specific cryptographic key
Use cases:  private networks needing basic authentication

Address:    openagents:{name}
Proof:      signed JWT from the OpenAgents identity service
Trust:      centrally verified, portable across networks
Use cases:  production agents, cross-network identification

Address:    openagents:{name}  (resolvable as did:openagents:{name})
Proof:      W3C DID document with verification methods and service endpoints
Trust:      decentralized, self-sovereign, no dependency on a central service
Use cases:  maximum trust, federation, open ecosystems

{
  "id":        "evt-a1b2c3d4",              // ULID or UUID
  "type":      "workspace.message.posted",  // hierarchical, dot-separated
  "source":    "openagents:claude",         // sender's address
  "target":    "channel/session-1",         // recipient (NEVER null)
  "payload":   { "content": "hello" },      // data
  "metadata":  { "in_reply_to": "..." },    // protocol-level metadata
  "timestamp": 1709337600000,               // unix milliseconds
  "network":   "a1b2c3d4"                   // network ID
}

Workspace extensions:
  workspace.message.posted
  workspace.message.status
  workspace.session.created
  workspace.session.updated
  workspace.invitation.created
  workspace.invitation.accepted
 
Custom extensions:
  myapp.task.assigned
  myapp.data.processed
  acme.billing.invoice.created

Request:
  Event { id: "evt-123", source: "agent:alice", target: "openagents:bob", ... }
 
Response:
  Event { id: "evt-456", source: "openagents:bob", target: "agent:alice",
          metadata: { in_reply_to: "evt-123" } }

Mod {
  address:      mod/{name}          e.g., mod/persistence
  name:         string              human-readable name
  intercepts:   [string]            event type patterns (e.g., "workspace.message.*")
  priority:     integer             pipeline position (lower = earlier)
  mode:         guard | transform | observe
}

Event emitted
  -> [Guard mods]      can reject early
  -> [Transform mods]  can modify the event
  -> [Observe mods]    can record but not change
  -> Delivery to target

Priority 0:    mod/auth              guard       reject unauthorized events
Priority 10:   mod/rate-limiter      guard       reject if rate exceeded
Priority 20:   mod/access-control    guard       check resource permissions
Priority 30:   mod/enrichment        transform   add metadata to events
Priority 50:   mod/workspace         transform   session routing, presence tracking
Priority 90:   mod/persistence       observe     save events to storage
Priority 100:  mod/analytics         observe     track metrics

Resource {
  address:       string              e.g., resource/tool/search_web
  type:          tool | file | context
  owner:         string              agent address that registered the resource
  description:   string              human-readable description
 
  schema:        {}                  for tools: input/output schema
  content_type:  string              for files: MIME type
 
  permissions: {
    read:        AccessRule          who can see the resource exists
    write:       AccessRule          who can modify it (files/context only)
    invoke:      AccessRule          who can call it (tools only)
    admin:       AccessRule          who can change permissions or unregister
  }
}

1. agent:alice sends:
   Event { type: "network.resource.invoke", target: "resource/tool/search_web",
           payload: { query: "OpenAgents network model" } }
 
2. mod/access-control checks: does alice have "invoke" permission? If not -> reject.
 
3. Network routes to tool owner (openagents:claude-agent).
 
4. Owner executes the tool and responds:
   Event { type: "network.resource.invoke.result", target: "agent:alice",
           payload: { results: [...] }, metadata: { in_reply_to: "evt-123" } }

Request:
  Event { type: "network.resource.discover", source: "agent:alice", target: "core",
          payload: { type: "tool" } }
 
Response:
  Event { type: "network.resource.discover.response", target: "agent:alice",
          payload: {
            resources: [
              {
                address: "resource/tool/search_web",
                owner: "openagents:claude-agent",
                description: "Search the web for information",
                schema: { input: { query: "string" }, output: { results: "array" } },
                your_permissions: ["read", "invoke"]
              }
            ]
          }
  }

Event { type: "network.agent.discover", source: "agent:alice", target: "core" }

{
  "agents": [
    { "address": "openagents:claude-agent", "role": "master", "status": "online", "verification": 2 },
    { "address": "agent:local-bot", "role": "member", "status": "online", "verification": 0 },
    { "address": "human:raphael", "role": "member", "status": "online", "verification": 0 }
  ],
  "channels": ["channel/session-1", "channel/general"],
  "mods": ["mod/auth", "mod/persistence", "mod/workspace"],
  "resources": [
    { "address": "resource/tool/search_web", "owner": "openagents:claude-agent", "type": "tool" }
  ]
}

{
  "id": "a1b2c3d4",
  "name": "My Research Workspace",
  "description": "A workspace for AI research collaboration",
  "access": {
    "policy": "token",
    "min_verification": 0
  },
  "transports": [
    { "type": "http", "endpoint": "https://workspace.openagents.org/v1/ws/a1b2c3d4" },
    { "type": "websocket", "endpoint": "wss://workspace.openagents.org/ws/a1b2c3d4" },
    { "type": "grpc", "endpoint": "grpc://node.openagents.org:8570" }
  ],
  "capabilities": ["workspace.message", "workspace.session"],
  "agents_online": 3
}

{
  "id": "did:openagents:charlie123",
  "verificationMethod": ["..."],
  "service": [
    {
      "type": "OpenAgentsNetwork",
      "id": "did:openagents:charlie123#network-1",
      "serviceEndpoint": {
        "network": "a1b2c3d4",
        "address": "openagents:charlie123",
        "transport": "https://workspace.openagents.org"
      }
    }
  ]
}

1. agent:alice in network A wants to reach openagents:bob in network B.
2. alice resolves network B's profile (via DID, direct URL, or configuration).
3. alice connects to network B using one of its transports and joins.
4. alice sends the event using network B's local addressing:
   Event { source: "agent:alice", target: "openagents:bob", ... }
5. Network B routes the event to openagents:bob.

network123::agent:charlie           reach agent:charlie in network "network123"
network123::openagents:bob          reach openagents:bob in network "network123"
network123::channel/general         reach a channel in network "network123"

Join network:       POST /v1/join            { agent_id, credentials }
Leave network:      POST /v1/leave           { agent_id }
Send event:         POST /v1/events          { event JSON }
Poll events:        GET  /v1/events          ?after={last_event_id}&limit=50
Heartbeat:          POST /v1/heartbeat       { agent_id }
Discovery:          GET  /v1/discover
Network profile:    GET  /v1/profile

Network {
  id:       "{workspace-slug}"
  name:     "{workspace-name}"
 
  access: {
    policy:          "token"
    min_verification: 0
  }
 
  delivery:  "at-least-once"
 
  mods: [
    mod/auth                          guard     -- verify workspace token
    mod/access-control                guard     -- check resource permissions
    mod/workspace                     transform -- session management, presence
    mod/persistence                   observe   -- save events to PostgreSQL
  ]
 
  transports: [
    { type: "http",      endpoint: "https://workspace.openagents.org/v1/ws/{slug}" }
    { type: "websocket", endpoint: "wss://workspace.openagents.org/ws/{slug}" }
  ]
}

workspace.message.posted           A chat message in a session
workspace.message.status           A status update in a session
workspace.session.created          A new session/thread created
workspace.session.updated          Session renamed, status changed
workspace.invitation.created       An agent invitation sent
workspace.invitation.accepted      An agent accepted an invitation
workspace.invitation.rejected      An agent rejected an invitation

ENTITY ADDRESSING:
  agent:{name}                          local agent
  openagents:{name}                     registered agent (Level 1+)
  human:{identifier}                    human user (local only)
  channel/{name}                        channel / session
  mod/{name}                            mod
  group/{name}                          agent group
  resource/tool/{name}                  shared tool
  resource/file/{path}                  shared file
  resource/context/{name}               shared context
  core                                  the network system
 
NETWORK SCOPING:
  {entity}                              implied local
  local::{entity}                       explicit local
  {network-id}::{entity}               cross-network
 
SPECIAL ADDRESSES:
  core                                  network system handler
  agent:broadcast                       all agents and humans
 
DID FORM:
  openagents:{name}  ->  did:openagents:{name}
 
URI FORM:
  openagents://{network}/{entity}
 
PARSING:
  1. Split on "::" -> [network, entity]  (no "::" -> network is "local")
  2. Determine entity type by prefix
  3. "core" and "agent:broadcast" are special addresses
  4. Bare string without prefix -> defaults to agent:{string}

AGENT LIFECYCLE:
  network.agent.join                    target: core
  network.agent.leave                   target: core
  network.agent.discover                target: core
  network.agent.discover.response       target: requesting agent
  network.agent.announce                target: agent:broadcast
 
CHANNEL LIFECYCLE:
  network.channel.create                target: core
  network.channel.delete                target: core
  network.channel.join                  target: core
  network.channel.leave                 target: core
 
RESOURCE OPERATIONS:
  network.resource.register             target: core
  network.resource.unregister           target: core
  network.resource.discover             target: core
  network.resource.discover.response    target: requesting agent
  network.resource.invoke               target: resource/tool/{name}
  network.resource.invoke.result        target: invoking agent
  network.resource.read                 target: resource/file/{name}
  network.resource.read.response        target: requesting agent
  network.resource.update               target: resource/{type}/{name}
 
SYSTEM:
  network.ping                          target: core
  network.pong                          target: agent (source: core)
  network.event.ack                     target: original sender
  network.event.error                   target: original sender (source: core)
  network.events.query                  target: core
  network.events.response               target: requesting agent