Aaditya Rajgor 打造 VAP，探索如何讓軟件更易供 AI 智能體使用

Most conversations about improving AI agents focus on the model: better reasoning, more context, better prompts.

I wanted to look at the software the agent interacts with.

If we could make that software easier for an AI model to use, what should it expose?

The answer that started this project was:

Its current state, available actions and the outcome of each action—in a consistent, verifiable way.

That became VAP: Verified Action Protocol, an open-source protocol and reference runtime. Its first experimental release is available, and I’m looking for developers to try it and tell me where the idea or implementation falls short.

Explore the repository

The problem: a tool response isn’t always an outcome

Imagine an agent creates an issue through an API.

The server creates it, but the connection drops before the response reaches the agent.

Now the agent has a timeout.

Did nothing happen? Did the issue get created? Should it retry?

A blind retry can create a duplicate. Claiming success would be guessing. And if the agent process restarts, it may lose the context needed to investigate.

This is one example of a broader problem: agents need a structured way to understand actions and their effects, including uncertainty.

What VAP does

VAP sits between an agent or application and its registered tools.

Developers describe the actions a tool supports, their expected effects, how to check the result and how to investigate an uncertain outcome.

VAP provides a shared place to:

• Prepare an action under scoped permissions.
• Record the intent before dispatch.
• Track execution separately from verification.
• Read back state and evaluate the defined checks.
• Reconcile uncertain operations before retrying.
• Keep an event history and evidence of what was checked.

“The action completed” and “the result was verified” are different states.

Here, verified means the configured checks passed on fresh evidence. It does not mean VAP can independently understand every business goal.

If the result cannot be established, VAP reports unknown.

The demo: lose the response, then find out what happened

The included demo uses a synthetic issue tracker. It deliberately creates an issue and drops the response.

VAP records the outcome as unknown. Reconciliation then finds the existing write, verification checks the saved result, and the operation becomes verified.

The destination records one write.

If the destination cannot provide enough evidence, the operation must remain unresolved. VAP does not promise universal exactly-once execution.

Try it

You’ll need Git, Docker with Compose v2 and an internet connection. The documented test platform is x86-64 Linux.

git clone https://github.com/arajgor1/verified-action-protocol.git
cd verified-action-protocol
docker compose -f examples/quickstart/compose.yaml run --rm demo

No model API key, GitHub credentials or cloud account is needed for this synthetic demo.

It demonstrates:

1. A verified action.
2. A lost response followed by reconciliation.
3. A partially applied batch followed by compensation as a separate operation.

To try the SDK connection example:

docker compose -f examples/quickstart/compose.yaml run --rm connect

When finished, remove the demo containers and database volume:

docker compose -f examples/quickstart/compose.yaml down -v

The quickstart uses evaluation-only authentication. It is not a production deployment configuration.

Where it fits

You run the VAP runtime with PostgreSQL and connect through the TypeScript SDK or the stdio MCP bridge.

The supported adapters cover configured HTTP actions and registered command-line recipes. Developers supply the tool-specific meaning and verification rules; VAP does not automatically discover how arbitrary software works.

Read the integration guide

What the testing actually showed

The synthetic fault comparison included a careful client with its own durable intent log.

That client matched VAP’s outcomes.

The value I’m exploring is making that discipline reusable: consistent action contracts, durable tracking, verification evidence and recovery behavior that each agent integration doesn’t have to implement from scratch.

VAP adds runtime overhead and integration work. Whether the shared infrastructure earns that cost is one of the questions I want feedback on.

This is 0.1.0-rc.1, an experimental release. Real-GitHub workflows and model-driven comparisons have not been validated. Browser support is excluded from the supported release, and the managed GCP path has an unresolved intermittent authentication failure.

Deployment restrictions and accepted security exceptions are documented in the repository.

What I’d like your feedback on

If you have a few minutes, try the demo and tell me:

Was it clear what VAP did—and what you still have to implement?

Where would it fit, or fail to fit, in your existing agent workflow?

Which real tool would you want to connect first?

If you already handle these problems with a durable workflow engine or your own client, I’d especially like to understand what VAP would need to offer to justify another component.

You can leave a comment here or open an issue.

The original question is still the one I’m exploring: how should software expose itself so an agent can act with clearer information and checkable results?