diff --git a/.github/workflows/links.yml b/.github/workflows/links.yml new file mode 100644 index 00000000..595fcf86 --- /dev/null +++ b/.github/workflows/links.yml @@ -0,0 +1,54 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025 Cisco and/or its affiliates. +# SPDX-License-Identifier: Apache-2.0 + +name: Links + +on: + repository_dispatch: + workflow_dispatch: + schedule: + - cron: "00 06 * * *" + +jobs: + linkChecker: + runs-on: ubuntu-latest + permissions: + issues: write + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + submodules: 'recursive' + + - name: Setup Golang + uses: actions/setup-go@v5 + with: + go-version: '1.23.1' + + - name: Setup Taskfile + shell: bash + run: | + sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin + + - name: Setup UV + shell: bash + run: | + curl -LsSf https://astral.sh/uv/install.sh | sh + + - name: Update GITHUB_PATH + shell: bash + run: echo "$HOME/.local/bin" >> $GITHUB_PATH + + - name: Build docs + shell: bash + run: | + task build + + - name: Link Checker + id: lychee + uses: lycheeverse/lychee-action@v2 + with: + args: '--config lychee.toml .build/site' + fail: false + diff --git a/.github/workflows/pr-links.yml b/.github/workflows/pr-links.yml new file mode 100644 index 00000000..d25c615c --- /dev/null +++ b/.github/workflows/pr-links.yml @@ -0,0 +1,72 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025 Cisco and/or its affiliates. +# SPDX-License-Identifier: Apache-2.0 + +name: PR Links + +on: + pull_request: + types: [opened, synchronize, reopened] + branches: [main, master] + workflow_dispatch: + +jobs: + linkChecker: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + submodules: 'recursive' + + - name: Setup Golang + uses: actions/setup-go@v5 + with: + go-version: '1.23.1' + + - name: Setup Taskfile + shell: bash + run: | + sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin + + - name: Setup UV + shell: bash + run: | + curl -LsSf https://astral.sh/uv/install.sh | sh + + - name: Update GITHUB_PATH + shell: bash + run: echo "$HOME/.local/bin" >> $GITHUB_PATH + + - name: Build docs + shell: bash + run: | + task build + + - name: Check links in PR changes + uses: lycheeverse/lychee-action@v2 + with: + # Remap live URLs to build directory because the links are potentially not live yet + args: | + --config lychee.toml + --root-dir $PWD/.build/site + --exclude-all-private + --remap 'https://docs\.agntcy\.org/(.*)/ file://'$PWD'/.build/site/$1/index.html' + .build/site/ + fail: true + output: lychee/out.md + + - name: Comment Broken Links + if: failure() + uses: marocchino/sticky-pull-request-comment@v2 + with: + path: lychee/out.md + + - name: Suggestions + if: failure() + run: | + echo -e "\nPlease review the links reported in the 'Check links in PR changes' step above." + echo -e "If a link is valid but fails due to a CAPTCHA challenge, IP blocking, login requirements, etc.," + echo -e "consider adding such links to lychee.toml exclude list to bypass future checks.\n" + exit 1 + diff --git a/.gitignore b/.gitignore index cfdf98a5..f808894f 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,6 @@ generated/ # Python cache __pycache__/ *.pyc + +# Lychee cache +.lycheecache diff --git a/.pymarkdown b/.pymarkdown index c0fa1a90..0316d1e0 100644 --- a/.pymarkdown +++ b/.pymarkdown @@ -8,12 +8,12 @@ plugins: enabled: true siblings_only: true md030: - enabled: true + enabled: false md031: enabled: false md033: - enabled: true - allowed_elements: [details, summary, img, br, sub, sup] + enabled: false + allowed_elements: [details, summary, img, br, sub, sup, div] md041: enabled: false md046: @@ -22,3 +22,7 @@ plugins: enabled: false md007: enabled: false + md034: + enabled: true + md036: + enabled: false diff --git a/Taskfile.yml b/Taskfile.yml index 255caedc..226693ca 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -52,12 +52,13 @@ tasks: - echo "All documentation tests passed!" lint: - desc: Run all linting checks (spelling, markdown) + desc: Run all linting checks (spelling, markdown, links) deps: - deps/patch cmds: - task: lint:spelling - task: lint:markdown + - task: lint:links lint:spelling: desc: Check spelling in documentation @@ -77,6 +78,12 @@ tasks: cmds: - uv run pymarkdown --config ../.pymarkdown scan ../docs + lint:links: + desc: Check for broken links in markdown documentation + internal: true + cmds: + - lychee --config lychee.toml docs/ + lint:fix: desc: Auto-fix spelling and markdown issues where possible deps: diff --git a/docs/coffee-agntcy/get-started.md b/docs/coffee-agntcy/get-started.md index 8cdcfe48..db2192d9 100644 --- a/docs/coffee-agntcy/get-started.md +++ b/docs/coffee-agntcy/get-started.md @@ -99,5 +99,4 @@ graph LR GC <--> TF[Tatooine Farm Agent] ``` - Learn more on how to deploy Lungo locally by visiting the [Lungo Deployment Guide](https://github.com/agntcy/coffeeAgntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/README.md) diff --git a/docs/coffee-agntcy/slim-coffee-agntcy.md b/docs/coffee-agntcy/slim-coffee-agntcy.md index 6271e1c4..d7078edc 100644 --- a/docs/coffee-agntcy/slim-coffee-agntcy.md +++ b/docs/coffee-agntcy/slim-coffee-agntcy.md @@ -23,14 +23,14 @@ transport = factory.create_transport("SLIM", endpoint=SLIM_ENDPOINT, name="defau Where: -* `AgntcyFactory` initializes the factory for the agent. -* `create_transport("SLIM", ...)` provisions a SLIM transport instance connected to the configured endpoint. +- `AgntcyFactory` initializes the factory for the agent. +- `create_transport("SLIM", ...)` provisions a SLIM transport instance connected to the configured endpoint. ## Sending Messages SLIM accommodates both targeted and broadcast messaging within the same API: -* **1-to-1 Message** +- **1-to-1 Message** Used when the supervisor agent needs to send a request to a single farm agent: @@ -38,7 +38,7 @@ SLIM accommodates both targeted and broadcast messaging within the same API: response = await client.send_message(request) ``` -* **Publisher/Subscriber Pattern** +- **Publisher/Subscriber Pattern** Used when the auction supervisor sends the same request to multiple farm agents and waits for all the responses: @@ -52,10 +52,10 @@ SLIM accommodates both targeted and broadcast messaging within the same API: Where: - * `broadcast_topic` is the topic to which the message is broadcasted. - * `recipients` is the list of agents to which the message is sent. + - `broadcast_topic` is the topic to which the message is broadcasted. + - `recipients` is the list of agents to which the message is sent. - ### Streaming Publisher/Subscriber + ### Streaming Publisher/Subscriber For real-time responses as farms reply, use the streaming variant: @@ -69,7 +69,7 @@ SLIM accommodates both targeted and broadcast messaging within the same API: This returns a stream of data from the farms. -* **Group Communication Pattern** +- **Group Communication Pattern** Used when multiple agents participate in a group chat session, where all agents can send messages and listen to communications from other agents in the group: @@ -85,13 +85,13 @@ SLIM accommodates both targeted and broadcast messaging within the same API: Where: - * `init_message` is the initial message to start the group chat. - * `group_channel` is the unique channel ID for the group chat session. - * `participants` is the list of agent topics participating in the group chat. - * `end_message` is the message that signals the end of the group chat. - * `timeout` is the timeout for the group chat session in seconds. + - `init_message` is the initial message to start the group chat. + - `group_channel` is the unique channel ID for the group chat session. + - `participants` is the list of agent topics participating in the group chat. + - `end_message` is the message that signals the end of the group chat. + - `timeout` is the timeout for the group chat session in seconds. - ### Streaming Group Communication + ### Streaming Group Communication For real-time order state transitions as each agent processes the order: diff --git a/docs/contributing.md b/docs/contributing.md index 32378990..990c85ca 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -8,8 +8,7 @@ reporting bugs that we ask you to review. Before reporting a new issue, please ensure that the issue was not already reported or fixed by searching through our [issues list](https://github.com/agntcy/docs/issues). -When creating a new issue, please be use the **New Issue** template, and provide as much relevant information as -possible. +When creating a new issue, use the **New Issue** template and provide as much relevant information as possible. ## Sending Pull Requests @@ -27,7 +26,7 @@ If you move or rename a documentation file, **you must add a redirect** to prese To add a redirect: -1. Open `mkdocs/mkdocs.yml` +1. Open `mkdocs/mkdocs.yml`. 1. Add an entry to the `redirect_maps` under the `redirects` plugin: ```yaml @@ -37,32 +36,48 @@ To add a redirect: 'old/path/to/file.md': 'new/path/to/file.md' ``` -1. Test the redirect locally by running `task build` or `task run` and verifying the old URL redirects to the new location +1. Test the redirect locally by running `task build` or `task run` and verifying the old URL redirects to the new location. !!! warning Failing to add redirects will result in broken links and a poor user experience. Always add redirects when moving content. +## Linting and Running the Documentation Site Locally + +The documentation site is built using [MkDocs](https://www.mkdocs.org/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). It also uses [Lychee](https://github.com/lycheeverse/lychee) to check for broken links and Taskfile to run the documentation site locally and lint the documentation. + +To run the documentation site locally and lint the documentation, you need the following prerequisites: + +- [Taskfile](https://taskfile.dev/) +- [Uv](https://docs.astral.sh/uv/getting-started/installation/) +- [Python version 3.13 or higher](https://www.python.org/) +- [Lychee](https://github.com/lycheeverse/lychee) + +To run the documentation site locally, use `task run`. This will start a live-reloading server at `http://localhost:8000`, allowing you to view the documentation site in your browser in real time. + +To lint and check for errors in the documentation, use `task lint`. This checks for broken links, spelling errors, and markdown syntax errors. + ## Markdown and Writing Style -Generic markdown intro (if needed): - - [commonmark.org/help/tutorial](https://commonmark.org/help/tutorial/) - - [www.markdownguide.org](https://www.markdownguide.org) +For a general overview of Markdown, see the following resources: + +- [commonmark.org/help/tutorial](https://commonmark.org/help/tutorial/) +- [www.markdownguide.org](https://www.markdownguide.org) -Don't add hard line breaks at a certain line-length, enable line-wrapping in your editor instead. Otherwise searching for sentences in the code becomes a pain. +Do not add hard line breaks at a certain line-length, enable line-wrapping in your editor instead. Otherwise searching for sentences in the code becomes a pain. ### Headings - Start with level 1 heading (#). - Use hashmarks for headings. -- Use title case (`# Start Every Word with Uppercase Except for Articles and Coordinating Conjunctions`) -- Keep titles reasonably short (they show up in the right-hand toc) +- Use title case (`# Start Every Word with Uppercase Except for Articles and Coordinating Conjunctions`). +- Keep titles reasonably short (they show up in the right-hand toc). - Do not skip heading levels. ### Lists -- Use dash (`-`) for bulleted lists -- Use only `1.` for ordered lists, they are automatically numbered in the output +- Use dash (`-`) for bulleted lists. +- Use only `1.` for ordered lists, they are automatically numbered in the output. - Indent additional stuff that belongs to a list element by 4 spaces, for example: ```md @@ -81,9 +96,14 @@ Don't add hard line breaks at a certain line-length, enable line-wrapping in you ### Links -- When linking to an external URL, or to a static HTML file within the project, use normal markdown linking `[text](url)` +- When linking to an external URL, or to a static HTML file within the project, use normal markdown linking `[text](url)`. - When linking to a file within the docs, use `[link text](/docs/path/to/file.md)`. -- Use project-absolute paths in the links/refs: start with a /, then the path relative to the `content` directory, for example: `/docs/getting-started/example.md` (easier to update when a file is moved, and easier to recognize where it is pointing). +- Use project-absolute paths in the links and references: start with a `/`, then the path relative to the `content` directory. + + !!! example + `/docs/getting-started/example.md` (easier to update when a file is moved, and easier to recognize where it is pointing). + +- Always check for broken links by running `task lint` before submitting a pull request. ### Images @@ -134,4 +154,4 @@ Is displayed as: This is a note. -For more information, see the [Material for MkDocs reference](https://squidfunk.github.io/mkdocs-material/reference/). +For more information on formatting, see the [Material for MkDocs reference](https://squidfunk.github.io/mkdocs-material/reference/). diff --git a/docs/dir/dir-api-reference.md b/docs/dir/dir-api-reference.md index 035785a3..244047ba 100644 --- a/docs/dir/dir-api-reference.md +++ b/docs/dir/dir-api-reference.md @@ -4,7 +4,7 @@ For detailed API reference, see the following pages: * [Core API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.core.v1) * [Events API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.events.v1) -* [Routing API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.routing.v1) +* [Routing API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.routing.v1) * [Search API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.search.v1) * [Sign API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.sign.v1) * [Store API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.store.v1) diff --git a/docs/dir/hosted-agent-directory.md b/docs/dir/hosted-agent-directory.md index 168cd8a5..d62c71c1 100644 --- a/docs/dir/hosted-agent-directory.md +++ b/docs/dir/hosted-agent-directory.md @@ -215,7 +215,7 @@ To be useful, an agent, A2A card, or MCP server record should include at least t * Skills, following the [OASF skills schema](https://schema.oasf.outshift.com/skills?extensions=). * Previous Record CID: if this is a new or related version to another record, indicate the CID of the related record. -And it will look like this: +And it will look like this: ```json { @@ -388,7 +388,6 @@ dir hub verify For further details on signing, use the `dirctl hub sign --help` command. - #### Pulling Agent Directory Records using `dirctl` You can also pull an Agent Directory record via `dirctl` using the command listed on the agent details page. diff --git a/docs/glossary.md b/docs/glossary.md index 404f95bd..7e403009 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -96,7 +96,7 @@ This glossary defines technical terms referenced across the SLIM messaging docum --- - Host:port (and scheme) on which a server listens or a client connects. Note that in the configuration the client needs to specify the protocol (e.g. http://localhost:46357), but not the server (e.g. localhost:46357) + Host:port (and scheme) on which a server listens or a client connects. Note that in the configuration the client needs to specify the protocol (e.g. `http://localhost:46357`), but not the server (e.g. localhost:46357) diff --git a/docs/identity/connecting_idp.md b/docs/identity/connecting_idp.md index bfcb35df..7d76ca06 100644 --- a/docs/identity/connecting_idp.md +++ b/docs/identity/connecting_idp.md @@ -172,4 +172,4 @@ Follow these steps to configure and register your Identity Provider: - Upon successful saving, your chosen Identity Provider will be registered and configured within AGNTCY Identity Service. - If you need to discard the entered information and cancel the creation process, click the **Cancel** button. -![Register Issuer With Ory Success](../assets/identity/identity_service/register-issuer-ory-done.png) \ No newline at end of file +![Register Issuer With Ory Success](../assets/identity/identity_service/register-issuer-ory-done.png) diff --git a/docs/identity/creating_identities.md b/docs/identity/creating_identities.md index f45edcb0..64556bb4 100644 --- a/docs/identity/creating_identities.md +++ b/docs/identity/creating_identities.md @@ -8,25 +8,25 @@ The first step involves defining your Agentic Service, which automatically creat **Steps:** -1. Navigate to **Agentic Services** in the left-hand menu. -2. Click on **Create Agentic Service**. -3. **Select Agentic Service Type & Source:** +1. Navigate to **Agentic Services** in the left-hand menu. +2. Click on **Create Agentic Service**. +3. **Select Agentic Service Type & Source:** - Choose the appropriate type for your service: - **OASF:** For Open Agent Schema defined services. - **MCP Server:** For services running on an MCP (Model Context Protocol) Server. _(As shown in the screenshot, this is the selected option.)_ - **A2A Protocol:** For Application-to-Application protocol services. - ![Create Agentic Service MCP Server](../assets/identity/identity_service/agentic-service-mcp.png) + ![Create Agentic Service MCP Server](../assets/identity/identity_service/agentic-service-mcp.png) -4. **Details:** +4. **Details:** - **Name:** Enter a descriptive name for your Agentic Service (e.g., "Currency Exchange MCP Server"). This name will help you identify the service within the platform. - **Description:** Provide a brief explanation of your service's purpose (e.g., "A Currency Exchange MCP Server"). - ![Create Agentic Service MCP Server](../assets/identity/identity_service/agentic-service-mcp-2.png) + ![Create Agentic Service MCP Server](../assets/identity/identity_service/agentic-service-mcp-2.png) -5. Click **Next** to proceed. Upon creation, an API Key will be generated for your Agentic Service. Ensure you securely store this API Key, as it will be required for issuing the badge. +5. Click **Next** to proceed. Upon creation, an API Key will be generated for your Agentic Service. Ensure you securely store this API Key, as it will be required for issuing the badge. - ![Create Agentic Service MCP Server](../assets/identity/identity_service/agentic-service-mcp-no-badge.png) + ![Create Agentic Service MCP Server](../assets/identity/identity_service/agentic-service-mcp-no-badge.png) ## 2. Issuing the Badge @@ -38,9 +38,9 @@ If your Agentic Service can be accessed directly from the public internet, you c **Steps:** -1. During the "Register Agentic Service" step, you will be prompted to provide the **Deployment URL** for your service. -2. Enter the full URL where your service is hosted and accessible. -3. The service will then perform online discovery using this URL. +1. During the "Register Agentic Service" step, you will be prompted to provide the **Deployment URL** for your service. +2. Enter the full URL where your service is hosted and accessible. +3. The service will then perform online discovery using this URL. ![Issue the Badge using the UI](../assets/identity/identity_service/issue-badge-online.png) @@ -50,9 +50,9 @@ For services that are not directly accessible from the public internet (e.g., se **Steps:** -1. **Install the Python SDK:** +1. **Install the Python SDK:** - Ensure you have the Python SDK installed. Refer to [the SDK section](./identity_service_sdk.md) of the documentation for detailed installation instructions. -2. **Perform the Badge Creation Command:** +2. **Perform the Badge Creation Command:** - Open your terminal or command prompt. - Execute the following command: ```bash @@ -100,4 +100,4 @@ The Policies Used By tab provides an overview of the policies used by the agent - **Updated At & Created At:** Timestamp details indicating when the policy was last updated or created. - **Action & Needs Approval:** Shows the allowed actions and whether approval is required or not. -![Policies Assigned to Agentic Service](../assets/identity/identity_service/agentic-service-mcp-badge-policies-usedby.png) \ No newline at end of file +![Policies Assigned to Agentic Service](../assets/identity/identity_service/agentic-service-mcp-badge-policies-usedby.png) diff --git a/docs/identity/creating_policies.md b/docs/identity/creating_policies.md index fd0c4878..d84a2cfd 100644 --- a/docs/identity/creating_policies.md +++ b/docs/identity/creating_policies.md @@ -30,7 +30,7 @@ The **AGNTCY Identity Service** leverages Task-Based Access Control (TBAC) to en 2. **Policy Details:** - - **Name:** Enter a descriptive name for your policy (e.g., "Email Policy"). + - **Name:** Enter a descriptive name for your policy (e.g., "Email Policy"). - **Assigned To:** Select the Agentic Service the policy will apply to (e.g., "SuperAgent"). - **Description:** Provide a brief description of the policy's purpose and scope. @@ -38,7 +38,7 @@ The **AGNTCY Identity Service** leverages Task-Based Access Control (TBAC) to en 3. **Policy Rules:** - - **Add Rule:** Define the specific actions and permissions associated with the policy. + - **Add Rule:** Define the specific actions and permissions associated with the policy. - **Name:** Specify the rule name (e.g., "Search & Read Emails"). - **Tasks:** Choose the tasks this rule will allow or restrict (e.g., "gmail_find_email"). - **Action:** Select the action type, such as "Allow" or "Deny". @@ -46,17 +46,17 @@ The **AGNTCY Identity Service** leverages Task-Based Access Control (TBAC) to en ![Policy Rule Creation](../assets/identity/identity_service/policies_03.png) ![Policy Rule Tasks Selection](../assets/identity/identity_service/policies_04.png) - ![Policy Rule Submittion](../assets/identity/identity_service/policies_05.png) + ![Policy Rule Submission](../assets/identity/identity_service/policies_05.png) 4. **Add Multiple Rules:** - - You can add additional rules by clicking "Add Rule" and repeating the steps above for each new rule. This is useful for complex policies requiring multiple permissions. + - You can add additional rules by clicking "Add Rule" and repeating the steps above for each new rule. This is useful for complex policies requiring multiple permissions. ![Multiple Rule Addition](../assets/identity/identity_service/policies_06.png) 5. **Review and Save Policy:** - - Review all policy details and rules to ensure accuracy. Once satisfied, click "Save" to finalize and save the policy. + - Review all policy details and rules to ensure accuracy. Once satisfied, click "Save" to finalize and save the policy. ![Review Policy](../assets/identity/identity_service/policies_07.png) ![Review Policy Rule Details](../assets/identity/identity_service/policies_08.png) @@ -79,7 +79,7 @@ The **AGNTCY Identity Service** leverages Task-Based Access Control (TBAC) to en 3. **Deleting Policies:** - - If a policy is no longer needed, select "Delete" from the options menu to remove it from the system. Confirm the deletion when prompted. + - If a policy is no longer needed, select "Delete" from the options menu to remove it from the system. Confirm the deletion when prompted. ## Best Practices diff --git a/docs/identity/identity_service.md b/docs/identity/identity_service.md index c55bb4ef..d440b488 100644 --- a/docs/identity/identity_service.md +++ b/docs/identity/identity_service.md @@ -13,8 +13,8 @@ Whether you are integrating existing services or deploying new ones, AGNTCY Iden To begin using AGNTCY Identity Service's features, you have two primary pathways: -1. **Verify Existing Identities**: If you already possess identity badges for your Agentic Services, you can use AGNTCY Identity Service to verify their authenticity and integrate them into the system. -2. **Register New Agentic Services**: For new deployments or services that require a fresh identity, AGNTCY Identity Service facilitates the registration process, allowing you to create and manage their digital presence. +1. **Verify Existing Identities**: If you already possess identity badges for your Agentic Services, you can use AGNTCY Identity Service to verify their authenticity and integrate them into the system. +2. **Register New Agentic Services**: For new deployments or services that require a fresh identity, AGNTCY Identity Service facilitates the registration process, allowing you to create and manage their digital presence. ### Get Started in 5 Minutes diff --git a/docs/identity/identity_service_api_access.md b/docs/identity/identity_service_api_access.md index 39ec9cbf..2bfa8c95 100644 --- a/docs/identity/identity_service_api_access.md +++ b/docs/identity/identity_service_api_access.md @@ -32,4 +32,4 @@ The Protodocs definitions for the Identity Service API can be accessed [here](ht The OpenAPI Client provides a way to interact with the Agent Identity API using standard HTTP requests. You can use any HTTP client library to make requests to the API endpoints defined in the OpenAPI specification. -The OpenAPI specification for the Agent Identity API can be found [here](./identity_service_api.md). \ No newline at end of file +The OpenAPI specification for the Agent Identity API can be found [here](./identity_service_api.md). diff --git a/docs/identity/identity_service_contributing.md b/docs/identity/identity_service_contributing.md index 87c2fab1..3d929e76 100644 --- a/docs/identity/identity_service_contributing.md +++ b/docs/identity/identity_service_contributing.md @@ -286,7 +286,7 @@ log.Info("Sharing some information") log.Error("Oh no! ", err) ``` -It is encouraged to exploit structured logging as much as possible, to add fields into the log simply use the `WithFields` function found in the same pacakge: +It is encouraged to exploit structured logging as much as possible, to add fields into the log simply use the `WithFields` function found in the same package: ```go log.WithFields(logrus.Fields{ @@ -305,7 +305,7 @@ log.WithError(err).Error("Oh no!") ## Contextual logging -For better and rich logs, it is highly recommanded to use a contextual logger which enriches the log with additional key-value pairs attached to `context.Context` (e.g, `tenantID`, `appID`, `requestID`, http & gRPC requests). +For better and rich logs, it is highly recommended to use a contextual logger which enriches the log with additional key-value pairs attached to `context.Context` (e.g, `tenantID`, `appID`, `requestID`, http & gRPC requests). For example: @@ -320,7 +320,7 @@ What log level to use? - **`log.Debug`:** Useful for times where verbosity is needed and for logs of high frequency, such as the ones used for debugging. - **`log.Info`:** Useful for giving a steady state information about the service and important log messages. - **`log.Warn`:** Logs that indicate a potential issue or a weird state but doesn't prevent the system from functioning. If used, it may require attention. -- **`log.Error`:** Error logs indicating unexpected behaviours occured somewhere in the code, most of these errors are not handled. +- **`log.Error`:** Error logs indicating unexpected behaviours occurred somewhere in the code, most of these errors are not handled. ## Error logging @@ -351,7 +351,7 @@ DEBUG[2025-10-06T10:45:13+02:00] Creating badge with claims full_method=/agntcy. > **Enabled for non development environment, such as production (`GO_ENV=production`)** -Each log is written in a JSON format, which is more effecient for parsing and to be fed to observability platforms such as Grafana. +Each log is written in a JSON format, which is more efficient for parsing and to be fed to observability platforms such as Grafana. Example: @@ -422,7 +422,7 @@ Only pull requests with passing unit tests are merged. - If table-driven tests aren't suitable: - Create one test function per test case, or - Use [`T.Run()`](https://pkg.go.dev/testing#T.Run) to create subtests within the same function. -- Arrange the body of the test using the "*Arrage -> Act -> Assert*" pattern: +- Arrange the body of the test using the "*Arrange -> Act -> Assert*" pattern: - **Arrange** your objects, data, and set them up as necessary. - **Act** on the code under test by executing it. - **Assert** the result based on what is expected. @@ -462,7 +462,7 @@ Only pull requests with passing unit tests are merged. When a test function covers a single scenario, its name should be composed of four parts: -1. **Struct name** - *(incude only if testing a struct method; omit for standalone functions)*. +1. **Struct name** - *(include only if testing a struct method; omit for standalone functions)*. 2. **Function/method name** - The specific function or method being tested. 3. **Expected behavior** - The outcome expected when the scenario is invoked, prefer the use of the verb `should`. 4. **Test scenario** - The specific condition or context in which the function/method is being tested. @@ -568,4 +568,4 @@ You can run coverage analysis using the `-cover` argument: ```sh go test ./... -cover -``` \ No newline at end of file +``` diff --git a/docs/identity/identity_service_development.md b/docs/identity/identity_service_development.md index d6c4ac17..dbdab373 100644 --- a/docs/identity/identity_service_development.md +++ b/docs/identity/identity_service_development.md @@ -15,7 +15,6 @@ Before you begin, ensure you have the necessary tools and access to the **AGNTCY Most of the development examples are provided in Python, but you can also use other programming languages to interact with the Agent Identity API. The endpoints are accessible via REST and gRPC protocols. To see more details about the API access, you can refer to the [API](./identity_service_api_access.md) section of the documentation. - ## Issuing and Verifying Badges ### Issuing a Badge @@ -88,13 +87,12 @@ In order to use `TBAC` effectively, you need to follow the following steps: NOTE The tasks available for `TBAC` are automatically discovered from the Agentic Services when you issue the badge. - -2. **Define the `TBAC` policies and rules for your Agentic Services.** +1. **Define the `TBAC` policies and rules for your Agentic Services.** - To integrate `TBAC` in your application, you can use the UI to define policies and rules for your Agentic Services. Please follow the detailed instructions in the [Policies and Rules Documentation](./creating_policies.md) to set up and manage access control for your services. -3. **Integrate `TBAC` in your application** following one of the methods below. +1. **Integrate `TBAC` in your application** following one of the methods below. ### A2A Integration using the Python SDK @@ -104,8 +102,7 @@ When using the Python SDK for `TBAC`, you need to provide in your environment th - `IDENTITY_SERVICE_API_KEY`: Your Agentic Service API Key. You can obtain this key from the Agent Services details page. - -##### Invoke using HTTPX Auth Class +#### Invoke using HTTPX Auth Class For HTTPX-based applications, you can use the `IdentityServiceAuth` class to integrate `TBAC`. This class provides an easy way to authorize Agentic Services and manage access tokens. @@ -181,11 +178,10 @@ When using the Python SDK for `TBAC`, you need to provide in your environment th - `IDENTITY_SERVICE_API_KEY`: Your Agentic Service API Key. You can obtain this key from the Agent Services details page. - -##### MCP ClientSession using HTTPX Auth Class +#### MCP ClientSession using HTTPX Auth Class For HTTPX-based applications, you can use the `IdentityServiceAuth` class to integrate `TBAC`. This class provides an easy way to authorize Agentic Services and manage access tokens. -Bellow you can find an example of how to use the `IdentityServiceAuth` class with HTTPX and Langchain's `MultiServerMCPClient` MCP adapter: +Below you can find an example of how to use the `IdentityServiceAuth` class with HTTPX and Langchain's `MultiServerMCPClient` MCP adapter: ```python # Other imports @@ -242,7 +238,7 @@ async def main(): ##### Authorize using the MCP Starlette/FastAPI auth middleware -For MCP(Model Context Protocl) based applications using Starlette, you can use the `IdentityServiceMCPAuthMiddleware` to integrate `TBAC`. This middleware automatically handles authorization for incoming requests: +For MCP(Model Context Protocol) based applications using Starlette, you can use the `IdentityServiceMCPAuthMiddleware` to integrate `TBAC`. This middleware automatically handles authorization for incoming requests: ```python # Other imports @@ -313,7 +309,6 @@ When using the REST APIs for `TBAC`, you need to replace the following variables - `REST_API_ENDPOINT`: The endpoint of the Agent Identity REST API. This can be obtained from the [API Access documentation](./identity_service_api_access.md). - `YOUR_AGENTIC_SERVICE_API_KEY`: Your Agentic Service API Key. You can obtain this key from the Agent Services details page. - The REST API provides endpoints to integrate `TBAC` in your application. You can follow these steps to authorize and verify Agentic Services: 1. **Authorize an Agentic Service** diff --git a/docs/identity/identity_service_protofiles.md b/docs/identity/identity_service_protofiles.md index 3f18b5ce..46db4df3 100644 --- a/docs/identity/identity_service_protofiles.md +++ b/docs/identity/identity_service_protofiles.md @@ -1,3 +1,3 @@ # Identity Service Protofiles -The Protodocs definitions for the Identity Service API can be accessed [here](https://github.com/agntcy/identity-service/tree/main/docs/protodocs/agntcy/identity/service). \ No newline at end of file +The Protodocs definitions for the Identity Service API can be accessed [here](https://github.com/agntcy/identity-service/tree/main/docs/protodocs/agntcy/identity/service). diff --git a/docs/identity/identity_service_sdk.md b/docs/identity/identity_service_sdk.md index b34129a1..c3457578 100644 --- a/docs/identity/identity_service_sdk.md +++ b/docs/identity/identity_service_sdk.md @@ -9,7 +9,6 @@ Agent Identity offers a Python SDK package allowing developers to use it as: To see more details about the development integration, you can refer to the [Dev section](./identity_service_development.md) section of the documentation. - ### Installation To install the Python SDK for Agent Identity, you can use pip: @@ -66,4 +65,4 @@ try: print("Badge issued successfully!") except Exception as e: print("Error issuing badge: ", e) -``` \ No newline at end of file +``` diff --git a/docs/identity/identity_service_settings.md b/docs/identity/identity_service_settings.md index 4da4a8a3..291d8699 100644 --- a/docs/identity/identity_service_settings.md +++ b/docs/identity/identity_service_settings.md @@ -108,7 +108,7 @@ Once a device is successfully added, you can view and manage it from the Devices ![Mobile Device Registered](../assets/identity/identity_service/Settings_DEVICE_10.png) -3. **Testing Device Notifications:** +2. **Testing Device Notifications:** - To ensure your device is receiving notifications correctly, you can send a test notification. - Locate the desired device in the list and click the options menu next to its entry. @@ -120,7 +120,7 @@ Once a device is successfully added, you can view and manage it from the Devices ![Mobile Device notification testing](../assets/identity/identity_service/Settings_DEVICE_12.png) -5. **Deleting a Device:** +1. **Deleting a Device:** - If a device is no longer needed or you wish to remove it from your account, you can delete it. - From the options menu next to the device entry, select Delete. diff --git a/docs/identity/vc_agent_badge.md b/docs/identity/vc_agent_badge.md index cd55887e..ce1f0f43 100644 --- a/docs/identity/vc_agent_badge.md +++ b/docs/identity/vc_agent_badge.md @@ -36,7 +36,7 @@ Where: ## A2A Agent Badge -Similarly, the example below shows a second Agent Badge, using in this case another definition, that is, an [A2A Agent Card](https://github.com/google/A2A/blob/main/specification/json/a2a.json#AgentCard) schema. +Similarly, the example below shows a second Agent Badge, using in this case another definition, that is, an [A2A Agent Card](https://a2a-protocol.org/latest/definitions/) schema. ```json CREDENTIAL @@ -66,7 +66,7 @@ CREDENTIAL Where: - `credentialSubject.id`: represents the [ID](identifiers.md#definitions) of the Agent subject. -- `credentialSubject.badge`: adheres to the [A2A Agent Card](https://github.com/google/A2A/blob/main/specification/json/a2a.json#AgentCard) schema. +- `credentialSubject.badge`: adheres to the [A2A Agent Card](https://a2a-protocol.org/latest/definitions/) schema. The `proof` in an Agent Badge can be verified using the `assertionMethod` defined in the `ResolverMetadata` object (various `ResolverMetadata` examples are available [here](./identifier_examples.md)). diff --git a/docs/identity/verify_identity.md b/docs/identity/verify_identity.md index c6240665..b3a41d8c 100644 --- a/docs/identity/verify_identity.md +++ b/docs/identity/verify_identity.md @@ -4,21 +4,21 @@ The "Verify Identity" screen allows users to verify a digital badge, typically a JOSE (JSON Object Signing and Encryption) enveloped badge. This screen is designed for quick and secure verification. -1. **Access the Screen**: Navigate to the "Verify Identity" page. +1. **Access the Screen**: Navigate to the "Verify Identity" page. - ![Verify Identity](../assets/identity/identity_service/verify-identity.png) + ![Verify Identity](../assets/identity/identity_service/verify-identity.png) -2. **Provide the Badge**: +2. **Provide the Badge**: - **Option A (File Upload)**: Click or drag and drop a JSON file (max 3MB) containing the JOSE enveloped badge into the "Details" area. - **Option B (Text Input)**: Paste the JOSE enveloped badge string directly into the "Badge" text field. - !!! note - We support both the JOSE enveloped badge or the full JSON badge content that you can obtain from the Agentic Services. The JOSE enveloped badge is a compact representation of the badge, while the full JSON badge contains all the details in a structured format. + !!! note + We support both the JOSE enveloped badge or the full JSON badge content that you can obtain from the Agentic Services. The JOSE enveloped badge is a compact representation of the badge, while the full JSON badge contains all the details in a structured format. -3. **Initiate Verification**: Click the "Verify" button. -4. **View Results**: The "Verification Results" section will populate with the outcome of the badge verification. +3. **Initiate Verification**: Click the "Verify" button. +4. **View Results**: The "Verification Results" section will populate with the outcome of the badge verification. - ![Verify Identity Results](../assets/identity/identity_service/verify-identity-done.png) + ![Verify Identity Results](../assets/identity/identity_service/verify-identity-done.png) ## Using the Python SDK diff --git a/docs/messaging/slim-authentication.md b/docs/messaging/slim-authentication.md index 297766f9..8723735f 100644 --- a/docs/messaging/slim-authentication.md +++ b/docs/messaging/slim-authentication.md @@ -47,11 +47,11 @@ This tutorial is based on the [SLIM examples](https://github.com/agntcy/slim/blo The following prerequisites are required: -- [Docker](https://docs.docker.com/get-docker/) -- [kubectl](https://kubernetes.io/docs/tasks/tools/) -- [Helm](https://helm.sh/docs/intro/install/) -- [KIND](https://kind.sigs.k8s.io/docs/user/quick-start/) -- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) +* [Docker](https://docs.docker.com/get-docker/) +* [kubectl](https://kubernetes.io/docs/tasks/tools/) +* [Helm](https://helm.sh/docs/intro/install/) +* [KIND](https://kind.sigs.k8s.io/docs/user/quick-start/) +* [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) Clone the SLIM repository if you haven't already: @@ -142,10 +142,10 @@ kubectl get pods -n slim We first provide a config for `spiffe-helper`, which retrieves SVIDs or JWTs from the SPIRE agent and writes them to disk. The key fields are: -- `agent_address`: Path to the SPIRE agent API socket. -- `cert_dir`: Where artifacts (cert, key, bundles, or JWTs) are written. -- `jwt_svids`: Audience and output filename for requested JWT SVIDs. -- `daemon_mode = true`: Run continuously to renew materials. +* `agent_address`: Path to the SPIRE agent API socket. +* `cert_dir`: Where artifacts (cert, key, bundles, or JWTs) are written. +* `jwt_svids`: Audience and output filename for requested JWT SVIDs. +* `daemon_mode = true`: Run continuously to renew materials. ```bash kubectl apply -f - < connection_config.json <` format. diff --git a/docs/oasf/contributing.md b/docs/oasf/contributing.md index e4dcc172..9d6ae226 100644 --- a/docs/oasf/contributing.md +++ b/docs/oasf/contributing.md @@ -111,8 +111,8 @@ populate it as described below. 3. `type`: Review OASF data_types and ensure you utilize appropriate types while defining new fields. - * All the available data_types can be accessed [here](https://schema.oasf.outshift.com/data_types). - * They are also accessible in your [local instance of the OASF server](http://localhost:8080/data_types). + - All the available data_types can be accessed [here](https://schema.oasf.outshift.com/data_types). + - They are also accessible in your [local instance of the OASF server](http://localhost:8080/data_types). 4. `is_array`: This a boolean key:value pair that you would need to add if the field you are defining is an array. #### Defining an `object` diff --git a/docs/oasf/decoding.md b/docs/oasf/decoding.md index ab8c2420..3c11fc98 100644 --- a/docs/oasf/decoding.md +++ b/docs/oasf/decoding.md @@ -44,7 +44,6 @@ func ProtoToStruct[T any](obj *structpb.Struct) (*T, error) Returns `*T`: Pointer to the converted Go struct. - ## `DecodeRecord` Decodes a record object into a structured format based on its schema version. diff --git a/docs/oasf/oasf-sdk.md b/docs/oasf/oasf-sdk.md index 27f51184..ef219789 100644 --- a/docs/oasf/oasf-sdk.md +++ b/docs/oasf/oasf-sdk.md @@ -32,7 +32,7 @@ docker run -p 31234:31234 ghcr.io/agntcy/oasf-sdk:latest ## Usage -The OASF SDK can be used in two ways: +The OASF SDK can be used in two ways: * As a Go Package you can import and use the packages directly in your Go application. * As a gRPC Service you can deploy the server and communicate via gRPC. diff --git a/docs/obs-and-eval/observe-and-eval.md b/docs/obs-and-eval/observe-and-eval.md index 460376ec..d6255ce1 100644 --- a/docs/obs-and-eval/observe-and-eval.md +++ b/docs/obs-and-eval/observe-and-eval.md @@ -2,7 +2,7 @@ ## Introduction -In the Internet of Agents (IoA) vision, multiple agents collaborate — making sequential and sometimes parallel decisions — forming a multi-agent system (MAS). As the number and complexity of involved agents increase, it becomes increasingly challenging to understand how the system arrived at a particular state. Unlike traditional software, a MAS is mode up of many independant agents, interacting in unpredictable way, making it hard to see how the information is shared, how decisions are made and how the system works as a whole. This is where *observability* comes in: it provides visibility into the execution of a MAS by recording each action taken, along with its outcome, by the agents. This yields a complete view of a run: what each agent did, which agents interacted, which tools were used, etc. Observability must extend beyond traditional monitoring to inculde instrumentation of communication and reasoning layers, to give insights into message flows, interaction patterns and the decision-making behind agent collaboration. +In the Internet of Agents (IoA) vision, multiple agents collaborate — making sequential and sometimes parallel decisions — forming a multi-agent system (MAS). As the number and complexity of involved agents increase, it becomes increasingly challenging to understand how the system arrived at a particular state. Unlike traditional software, a MAS is mode up of many independent agents, interacting in unpredictable way, making it hard to see how the information is shared, how decisions are made and how the system works as a whole. This is where *observability* comes in: it provides visibility into the execution of a MAS by recording each action taken, along with its outcome, by the agents. This yields a complete view of a run: what each agent did, which agents interacted, which tools were used, etc. Observability must extend beyond traditional monitoring to include instrumentation of communication and reasoning layers, to give insights into message flows, interaction patterns and the decision-making behind agent collaboration. While observability provides *factual information* about a MAS, *evaluation* judges its *quality and effectiveness*. Using the data produced by observability, evaluation surfaces performance through metrics that measure dimensions important to the user. For example, metrics can measure the relevance of the final output relative to the initial input, or the overall efficiency of the workflow (were there unnecessary loops during execution?). In effect, evaluation transforms raw telemetry into performance, reliability, cost-efficiency, and security signals. Evaluation can also be applied across multiple sessions (executions) over time to identify trends or performance decay. diff --git a/lychee.toml b/lychee.toml new file mode 100644 index 00000000..143d0f20 --- /dev/null +++ b/lychee.toml @@ -0,0 +1,72 @@ +# Lychee Link Checker Configuration +# https://github.com/lycheeverse/lychee + +# Maximum number of concurrent network requests +max_concurrency = 10 + +# Request timeout in seconds +timeout = 10 + +# Accept these HTTP status codes as valid +accept = [200, 201, 204, 403, 429, 503] + +# Exclude URL patterns (regex) +exclude = [ + # Local development URLs + 'localhost', + 'http://127\.0\.0\.1', + 'https://127\.0\.0\.1', + 'http://0\.0\.0\.0', + 'host\.docker\.internal', + + # Well-known endpoints and example domains + '\.well-known', + 'api\.node', + 'https://api\.NODE', + + # Self-referential docs URLs (may not exist yet) + 'https://docs\.agntcy\.org/.*', + + # GitHub raw URLs that are generated but may not exist + 'https://github\.com/agntcy/docs/raw/main/docs/.*', + + # Example/placeholder URLs used in documentation + 'example\.com', + 'your-username', + 'company\.com', + 'remote-slim', + 'otel-collector', + 'slim\.slim', + 'schema\.oasf\.agntcy\.org', + 'api\.agent-identity\.outshift\.com', + 'token\.actions\.githubusercontent\.com', + 'github\.com/example/', + 'spiffe\.github\.io/helm-charts-hardened', + + # Sites that timeout from GitHub Actions IPs + 'w3\.org', + 'gnu\.org', +] + +# Exclude paths (glob patterns relative to the input) +exclude_path = ['overrides'] + +# Enable link caching for faster subsequent runs +cache = true + +# Only show errors and summary (not every checked link) +# Set to "info" or "debug" for more verbose output +# Omit or set to false for minimal output + +# Maximum number of retries per link +max_retries = 2 + +# HTTP method to use for checking links +method = "get" + +# Exclude links from code blocks, preformatted text, and other verbatim content +include_verbatim = false + +# User agent string +user_agent = "lychee/agntcy-docs" + diff --git a/mkdocs/mkdocs.yml b/mkdocs/mkdocs.yml index 892ff86f..8566ae20 100644 --- a/mkdocs/mkdocs.yml +++ b/mkdocs/mkdocs.yml @@ -50,39 +50,6 @@ plugins: - griffe_pydantic: schema: true swagger-ui-tag: - htmlproofer: - ignore_urls: - # Local development URLs - - "http://localhost*" - - "https://localhost*" - - "*127.0.0.1*" - - # Generic file patterns and placeholders - - "*/screenshot.png" - - "*/image.png" - - "*/docs/path/to/file.md" - - "https://api.NODE/*" - - # External URLs with false negatives (rate limiting/blocking) - - "https://docs.agntcy.org/*" - - "https://www.npmjs.com/" - - "https://httpbin.org/" - - # Auto-generated anchors from API documentation - - "#agntcy*" # Covers all agntcy protobuf types - - "#google*" # Covers all Google protobuf types - - "#uint32" - - "#string" - - "#bytes" - - "#bool" - - "#top" - - # Cross-file API references (both source and build formats) - - "dir-*-v1-api.md#*" # Source format - - "../dir-*-v1-api/#*" # Build format - raise_error: false - raise_error_after_finish: false - validate_external_urls: true include-markdown: theme: