Metadata-Version: 2.5
Name: marshal-ledger
Version: 0.9.0
Summary: Marshal agent ledger: an open-source, self-hosted AI agent inventory for Copilot Studio, Agentforce, Bedrock, Databricks and agent code.
Project-URL: Homepage, https://github.com/marshal-ledger/marshal
Project-URL: Documentation, https://marshal-ledger.github.io/marshal/
Project-URL: Live demo, https://marshal-ledger.github.io/marshal/demo/
Project-URL: Changelog, https://github.com/marshal-ledger/marshal/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/marshal-ledger/marshal/issues
Author: Marshal contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent-inventory,agent-registry,agent-spec,agentforce,ai-agents,ai-governance,audit,bedrock,bedrock-agents,copilot-studio,crewai,databricks,drift-detection,google-adk,governance,langchain,langgraph,oasf,openai-agents,terraform,vertex-ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Provides-Extra: azure
Requires-Dist: azure-identity>=1.13; extra == 'azure'
Provides-Extra: dev
Requires-Dist: cfn-lint>=1.58; extra == 'dev'
Requires-Dist: fastapi>=0.110; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: jsonschema>=4.21; extra == 'dev'
Requires-Dist: psycopg[binary]>=3.1; extra == 'dev'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: uvicorn>=0.29; extra == 'dev'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == 'server'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'server'
Requires-Dist: uvicorn>=0.29; extra == 'server'
Description-Content-Type: text/markdown

<img src="https://raw.githubusercontent.com/marshal-ledger/marshal/main/docs/assets/marshal-logo.svg" width="72" height="72" alt="Marshal logo">

# Marshal — an agent ledger

[![PyPI](https://img.shields.io/pypi/v/marshal-ledger)](https://pypi.org/project/marshal-ledger/)
[![Python](https://img.shields.io/pypi/pyversions/marshal-ledger)](https://pypi.org/project/marshal-ledger/)
[![Tests](https://github.com/marshal-ledger/marshal/actions/workflows/test.yml/badge.svg)](https://github.com/marshal-ledger/marshal/actions/workflows/test.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/marshal-ledger/marshal/blob/main/LICENSE)

An open-source AI agent inventory for the enterprise: one versioned record of every agent on Copilot Studio, Agentforce, Bedrock, Databricks and agent code, with risk-ranked diffs, drift, dependencies and audit evidence. Any format in, any format out. It runs inside your network, uses no AI and needs no platform credentials.

**[Live demo](https://marshal-ledger.github.io/marshal/demo/)** · **[Documentation](https://marshal-ledger.github.io/marshal/)** · **[Getting started](https://github.com/marshal-ledger/marshal/blob/main/docs/getting-started.md)**

Marshal reads the agent definitions teams already produce: Databricks bundles, Copilot Studio agents, Bedrock templates, Agentforce metadata, agent code and the open standards. It builds a normalized, versioned record of every agent: what model it asks for, what tools and data it can reach, and who it acts as. Every field says where its value came from, and nothing is guessed.

<img src="https://raw.githubusercontent.com/marshal-ledger/marshal/main/docs/assets/web-tour.gif" alt="A walk through the Marshal web view: the inventory of 29 public agents, a Copilot Studio agent in drift whose tool was switched to the maker's credentials, a proposed change that adds a refund function, and the agents that share an Apex action">

**Status:** alpha. Before 1.0 a minor release may change the ledger model, the ingest API or the command line; the [changelog](https://github.com/marshal-ledger/marshal/blob/main/CHANGELOG.md) lists each such change.

## What it does

- **Inventory** of every agent across platforms, with versions, deployments, and each record's completeness.
- **Risk-ranked review:** pull requests that change an agent get a comment that lists permission escalations, new write tools and removed guardrails first.
- **Drift and freshness:** compares what is live with what was shipped, and shows how recently each record was confirmed and by which channel.
- **Dependencies:** "who uses this tool, this knowledge source, this permission?" Refs on other platforms that reach the same HTTP operation, MCP server, knowledge URL or API host are listed too, each with how it matched.
- **Translation** between formats, with a fidelity report computed by reading the result back.
- **Portability scores** for moving an agent to another platform, from a community-maintained capability matrix.

## Easy to approve

Most tools that touch AI agents raise questions in a security review. Marshal is built so it doesn't:

- **It runs inside your network.** You host it, on your own database. There is no Marshal cloud service, so the agent definitions, instructions and permissions it records never go to a vendor. The service's only outbound requests fetch your CI provider's public signing keys.
- **It uses no AI.** Marshal reads definitions with ordinary parsers and fixed, documented rules. It never sends your agents' instructions, tools or permissions to a language model, so there is no AI system to evaluate before you approve it.
- **It needs no platform credentials.** Your existing CI pipelines push definitions to Marshal, signed in with their own short-lived OIDC tokens. Marshal never connects to Copilot Studio, Bedrock or any other platform where your agents live, so it holds no keys to them.

The [security review](https://github.com/marshal-ledger/marshal/blob/main/docs/security-review.md) covers what Marshal stores, what it connects to, and how releases are signed.

## How it runs

<img src="https://raw.githubusercontent.com/marshal-ledger/marshal/main/docs/assets/architecture.svg" alt="How Marshal runs: agent definitions in repositories and web designers reach your CI pipelines, which push proposed, shipped and observed events to Marshal's ingest API with their OIDC token. Marshal records them in the ledger, and teams see risk-ranked pull request comments, the web view and the CLI. Marshal never connects to an agent platform.">

Pipelines you already run record each agent: a pull request records the proposed definition and gets a comment ranking its changes, a deploy records what was shipped, and an optional scheduled export records what is live in a web designer. See the [GitHub Action](https://github.com/marshal-ledger/marshal/blob/main/docs/github-action.md), [GitLab CI](https://github.com/marshal-ledger/marshal/blob/main/docs/gitlab-ci.md), [Jenkins and Azure DevOps](https://github.com/marshal-ledger/marshal/blob/main/docs/other-ci.md) and [Deployment](https://github.com/marshal-ledger/marshal/blob/main/docs/deployment.md).

## Formats

| Source | Read | Write | Writer tested by |
|---|---|---|---|
| Databricks Asset Bundles (Genie spaces, agent apps) | ✓ | |  |
| AWS CloudFormation and CDK (Bedrock Agents, AgentCore harnesses and runtimes) | ✓ | Bedrock Agents, AgentCore harness | cfn-lint; Bedrock Agents deployed |
| Terraform plan and state (Bedrock Agents, AgentCore harnesses and runtimes; AWS and Cloud Control providers) | ✓ | | |
| AgentCore CLI projects (AgentCore harnesses) | ✓ | | |
| Microsoft Copilot Studio (agent workspaces, solutions) | ✓ | ✓ | published schema, partly |
| Salesforce Agentforce (Agent Script, legacy metadata) | ✓ | Agent Script | round trip |
| Google ADK Agent Config | ✓ | ✓ | published schema; loads in ADK |
| Vertex AI Agent Engine (saved API responses) | inventory | |  |
| Python agent code (OpenAI Agents SDK, LangChain/LangGraph, Google ADK, CrewAI, direct model API calls) | ✓ | |  |
| ADL, Open Agent Spec, AGNTCY OASF | ✓ | ✓ | round trip; published schema for ADL and Agent Spec |
| Marshal file: a hand-written definition for agents no reader covers, recorded as attested | ✓ | ✓ | round trip |

Readers are tested against real, public definitions, pinned to a commit. Only the Bedrock writer's output has been deployed to its platform so far; see [how each format is verified](https://github.com/marshal-ledger/marshal/blob/main/docs/design.md#formats-and-how-each-is-verified), and [supported versions](https://github.com/marshal-ledger/marshal/blob/main/docs/formats/supported-versions.md) for the variants each reader handles.

## Try it

Browse the [live demo](https://marshal-ledger.github.io/marshal/demo/), or build it yourself from 29 public agents, with nothing to install but [uv](https://docs.astral.sh/uv/):

```console
$ uvx --from 'marshal-ledger[server]' marshal demo
$ uvx --from 'marshal-ledger[server]' marshal web --db demo.sqlite
```

Or `pip install 'marshal-ledger[server]'`, then `marshal demo` and `marshal web --db demo.sqlite`. `marshal demo` downloads the agents' definitions from their public GitHub repositories, pinned to a commit.

Then on your own agents. See [Getting started](https://github.com/marshal-ledger/marshal/blob/main/docs/getting-started.md):

```console
$ marshal read path/to/bundle                        # print ledger records
$ marshal collect path/to/bundle --target prod --event shipped
$ marshal ls                                         # every agent, latest version, where it is shipped
$ marshal diff my-team/my_agent                      # proposed against shipped, ranked by risk
$ marshal status my-team/my_agent                    # shipped vs live per environment, drift, freshness
$ marshal deps "*my_tool" --shipped                  # who depends on this, and where it is live
$ marshal convert agent.adl.yaml --to agent-spec     # translate, with a fidelity report
$ marshal port my-team/my_agent --to all             # portability to every platform
$ marshal web                                        # browse the store
```

`collect` writes to a local SQLite store (`marshal.sqlite`, or `--db` / `$MARSHAL_DB`). In a shared deployment, pipelines run `marshal push`, the [GitHub Action](https://github.com/marshal-ledger/marshal/blob/main/docs/github-action.md) or the [GitLab CI template](https://github.com/marshal-ledger/marshal/blob/main/docs/gitlab-ci.md) against the [ingest API](https://github.com/marshal-ledger/marshal/blob/main/docs/ingest-server.md). Optional [scheduled workflows](https://github.com/marshal-ledger/marshal/blob/main/examples/scheduled/) export agents built in a web designer, such as Copilot Studio and Agentforce, and report drift from what was shipped.

## Documentation

The documentation is published at [marshal-ledger.github.io/marshal](https://marshal-ledger.github.io/marshal/).

- [Getting started](https://github.com/marshal-ledger/marshal/blob/main/docs/getting-started.md)
- Guides: [Copilot Studio inventory](https://github.com/marshal-ledger/marshal/blob/main/docs/guides/copilot-studio-inventory.md), [pull request review](https://github.com/marshal-ledger/marshal/blob/main/docs/guides/pull-request-review.md), [agents in code](https://github.com/marshal-ledger/marshal/blob/main/docs/guides/agents-in-code.md), [drift](https://github.com/marshal-ledger/marshal/blob/main/docs/guides/drift-detection.md), [ADK to Agent Spec](https://github.com/marshal-ledger/marshal/blob/main/docs/guides/convert-adk-to-agent-spec.md), [Bedrock Agents to AgentCore](https://github.com/marshal-ledger/marshal/blob/main/docs/guides/bedrock-agents-to-agentcore.md), [audit evidence](https://github.com/marshal-ledger/marshal/blob/main/docs/guides/audit-evidence.md)
- [How Marshal compares](https://github.com/marshal-ledger/marshal/blob/main/docs/comparison.md) with cloud agent registries, platform admin tools, observability, AI gateways and governance platforms
- [Design](https://github.com/marshal-ledger/marshal/blob/main/docs/design.md): the problem, architecture, security and network posture, roadmap
- [Ledger model v0](https://github.com/marshal-ledger/marshal/blob/main/docs/ledger-model.md): records, provenance, version hashing, the version store, risk ranking, freshness
- [Conversion and fidelity](https://github.com/marshal-ledger/marshal/blob/main/docs/conversion.md) and [Portability](https://github.com/marshal-ledger/marshal/blob/main/docs/portability.md)
- Formats: [Databricks](https://github.com/marshal-ledger/marshal/blob/main/docs/formats/databricks.md), [CloudFormation](https://github.com/marshal-ledger/marshal/blob/main/docs/formats/cloudformation.md), [Terraform](https://github.com/marshal-ledger/marshal/blob/main/docs/formats/terraform.md), [AgentCore CLI](https://github.com/marshal-ledger/marshal/blob/main/docs/formats/agentcore-cli.md), [Copilot Studio](https://github.com/marshal-ledger/marshal/blob/main/docs/formats/copilot-studio.md), [Agentforce](https://github.com/marshal-ledger/marshal/blob/main/docs/formats/agentforce.md), [ADK Agent Config](https://github.com/marshal-ledger/marshal/blob/main/docs/formats/adk-config.md), [Vertex AI Agent Engine](https://github.com/marshal-ledger/marshal/blob/main/docs/formats/vertex-agent-engine.md), [Python agent code](https://github.com/marshal-ledger/marshal/blob/main/docs/formats/python.md), [ADL](https://github.com/marshal-ledger/marshal/blob/main/docs/formats/adl.md), [Agent Spec](https://github.com/marshal-ledger/marshal/blob/main/docs/formats/agent-spec.md), [OASF](https://github.com/marshal-ledger/marshal/blob/main/docs/formats/oasf.md), [Marshal file](https://github.com/marshal-ledger/marshal/blob/main/docs/formats/marshal-file.md)
- [Platform exportability](https://github.com/marshal-ledger/marshal/blob/main/docs/platform-exportability.md): what each closed platform exposes
- [Ingest API](https://github.com/marshal-ledger/marshal/blob/main/docs/ingest-server.md), [GitHub Action](https://github.com/marshal-ledger/marshal/blob/main/docs/github-action.md), [GitLab CI](https://github.com/marshal-ledger/marshal/blob/main/docs/gitlab-ci.md), [Jenkins and Azure DevOps](https://github.com/marshal-ledger/marshal/blob/main/docs/other-ci.md) and [Deployment](https://github.com/marshal-ledger/marshal/blob/main/docs/deployment.md)
- [Security review](https://github.com/marshal-ledger/marshal/blob/main/docs/security-review.md): what is stored, authentication, network, supply chain, retention and audit, for security reviewers

## Development

```console
$ pip install -e '.[dev]'
$ python scripts/fetch_fixtures.py     # golden fixtures: real public agent definitions, pinned by commit
$ pytest
```

See [Contributing](https://github.com/marshal-ledger/marshal/blob/main/CONTRIBUTING.md). Golden fixtures are fetched rather than committed, so each file stays under its upstream license. After changing the model, regenerate the schema with `python scripts/generate_schema.py`. Report vulnerabilities as described in [Security](https://github.com/marshal-ledger/marshal/blob/main/SECURITY.md).

## License

Marshal is licensed under the [Apache License 2.0](https://github.com/marshal-ledger/marshal/blob/main/LICENSE).
