Skip to content

feat(docs): add event system and CLI documentation #285

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tkircsi merged 2 commits into from
Oct 22, 2025
Merged

feat(docs): add event system and CLI documentation #285

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ffcd096
add event system and CLI documentation
tkircsi Oct 18, 2025
ddacdc8
chore: editorial review
keraron Oct 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/dir/.index
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,13 @@ nav:
- Trust Model: trust-model.md
- Getting Started: getting-started.md
- Features and Usage: scenarios.md
- Event Streaming: events.md
- Hosted AGNTCY Agent Directory: hosted-agent-directory.md
- CLI Reference: directory-cli.md
- SDK Reference: directory-sdk.md
- API Reference:
- Core: dir-core-v1-api.md
- Events: dir-events-v1-api.md
- Routing: dir-routing-v1-api.md
- Search: dir-search-v1-api.md
- Sign: dir-sign-v1-api.md
Expand Down
119 changes: 119 additions & 0 deletions docs/dir/dir-events-v1-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
# Protocol Documentation
<a name="top"></a>

## Table of Contents

- [agntcy/dir/events/v1/event_service.proto](#agntcy_dir_events_v1_event_service-proto)
- [Event](#agntcy-dir-events-v1-Event)
- [ListenRequest](#agntcy-dir-events-v1-ListenRequest)
- [ListenResponse](#agntcy-dir-events-v1-ListenResponse)
- [EventType](#agntcy-dir-events-v1-EventType)
- [EventService](#agntcy-dir-events-v1-EventService)

- [Scalar Value Types](#scalar-value-types)

<a name="agntcy_dir_events_v1_event_service-proto"></a>
<p align="right"><a href="#top">Top</a></p>

## agntcy/dir/events/v1/event_service.proto

<a name="agntcy-dir-events-v1-Event"></a>

### Event
Event represents a system event that occurred.

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| id | [string](#string) | | Unique event identifier (generated by the system). |
| type | [EventType](#agntcy-dir-events-v1-EventType) | | Type of event that occurred. |
| timestamp | [google.protobuf.Timestamp](#google-protobuf-Timestamp) | | When the event occurred. |
| resource_id | [string](#string) | | Resource identifier (CID for records, sync_id for syncs, etc.). |
| labels | [string](#string) | repeated | Optional labels associated with the record (for record events). |
| metadata | [Event.MetadataEntry](#agntcy-dir-events-v1-Event-MetadataEntry) | repeated | Optional metadata for additional context. Used for flexible event-specific data that doesn't fit standard fields. |

<a name="agntcy-dir-events-v1-Event-MetadataEntry"></a>

### Event.MetadataEntry

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| key | [string](#string) | | |
| value | [string](#string) | | |

<a name="agntcy-dir-events-v1-ListenRequest"></a>

### ListenRequest
ListenRequest specifies filters for event subscription.

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| event_types | [EventType](#agntcy-dir-events-v1-EventType) | repeated | Event types to subscribe to. If empty, subscribes to all event types. |
| label_filters | [string](#string) | repeated | Optional label filters (e.g., "/skills/AI", "/domains/research"). Only events for records matching these labels are delivered. Uses substring matching. |
| cid_filters | [string](#string) | repeated | Optional CID filters. Only events for specific CIDs are delivered. |

<a name="agntcy-dir-events-v1-ListenResponse"></a>

### ListenResponse
ListenResponse is the response message for the Listen RPC.
Wraps the Event message to allow for future extensions without breaking the Event structure.

| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| event | [Event](#agntcy-dir-events-v1-Event) | | The event that occurred. |

<a name="agntcy-dir-events-v1-EventType"></a>

### EventType
EventType represents all valid event types in the system.
Each value represents a specific operation that can occur.

Supported Events:
- Store: RECORD_PUSHED, RECORD_PULLED, RECORD_DELETED
- Routing: RECORD_PUBLISHED, RECORD_UNPUBLISHED
- Sync: SYNC_CREATED, SYNC_COMPLETED, SYNC_FAILED
- Sign: RECORD_SIGNED

| Name | Number | Description |
| ---- | ------ | ----------- |
| EVENT_TYPE_UNSPECIFIED | 0 | Unknown/unspecified event type. |
| EVENT_TYPE_RECORD_PUSHED | 1 | Store service events - record storage operations<br/><br/>A record was pushed to local storage. |
| EVENT_TYPE_RECORD_PULLED | 2 | A record was pulled from storage. |
| EVENT_TYPE_RECORD_DELETED | 3 | A record was deleted from storage. |
| EVENT_TYPE_RECORD_PUBLISHED | 4 | Routing service events - network operations<br/><br/>A record was published/announced to the network. |
| EVENT_TYPE_RECORD_UNPUBLISHED | 5 | A record was unpublished from the network. |
| EVENT_TYPE_SYNC_CREATED | 6 | Sync service events - synchronization operations<br/><br/>A sync operation was created/initiated. |
| EVENT_TYPE_SYNC_COMPLETED | 7 | A sync operation completed successfully. |
| EVENT_TYPE_SYNC_FAILED | 8 | A sync operation failed. |
| EVENT_TYPE_RECORD_SIGNED | 9 | Sign service events - cryptographic operations<br/><br/>A record was signed. |

<a name="agntcy-dir-events-v1-EventService"></a>

### EventService
EventService provides real-time event streaming for all system operations.
Events are delivered from subscription time forward with no history or replay.
This service enables external applications to react to system changes in real-time.

| Method Name | Request Type | Response Type | Description |
| ----------- | ------------ | ------------- | ------------|
| Listen | [ListenRequest](#agntcy-dir-events-v1-ListenRequest) | [ListenResponse](#agntcy-dir-events-v1-ListenResponse) stream | Listen establishes a streaming connection to receive events. Events are only delivered while the stream is active. On disconnect, missed events are not recoverable. |

## Scalar Value Types

| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
| ----------- | ----- | --- | ---- | ------ | -- | -- | --- | ---- |
| <a name="double" /> double | | double | double | float | float64 | double | float | Float |
| <a name="float" /> float | | float | float | float | float32 | float | float | Float |
| <a name="int32" /> int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| <a name="int64" /> int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| <a name="uint32" /> uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
| <a name="uint64" /> uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
| <a name="sint32" /> sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| <a name="sint64" /> sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| <a name="fixed32" /> fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) |
| <a name="fixed64" /> fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum |
| <a name="sfixed32" /> sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| <a name="sfixed64" /> sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| <a name="bool" /> bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass |
| <a name="string" /> string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
| <a name="bytes" /> bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |

Loading
Loading