DEV Community

Indu Das
Indu Das

Posted on

FreshCtx 0.5.0: protecting Agno tools from stale external evidence

#ai #agents #python #opensource

FreshCtx 0.5.0 is now public.

This release adds an optional integration for Agno 2.9. The integration places FreshCtx at Agno's actual tool boundary, where it can re-check the external evidence that an application declared when it made a decision.

The problem is simple:

  1. An agent reads a deployment state, account status, API response, approval, or other mutable source.
  2. It reasons from that source.
  3. The source changes before the tool executes.
  4. The old decision still looks locally reasonable, but it is no longer based on current evidence.

What the Agno hook does

FreshCtx now provides synchronous and asynchronous Agno hooks.

The hook runs immediately before the tool body. If a declared dependency changed, or cannot be verified under the configured blocking policy, FreshCtx stops execution before the side effect occurs.

Install it with:

python -m pip install 'freshctx[agno]==0.5.0'
Enter fullscreen mode Exit fullscreen mode

A tool can attach the boundary directly:

from freshctx.integrations.agno import agno_tool_hook

freshness_hook = agno_tool_hook(
    depends_on=[decision],
    store=store,
    audit_path="freshctx-agno-audit.jsonl",
)

@tool(tool_hooks=[freshness_hook])
def deploy(target: str) -> str:
    return f"deployed:{target}"
Enter fullscreen mode Exit fullscreen mode

This is deliberately narrow. FreshCtx does not repair Agno's internal run state and does not replace transactions, idempotency, concurrency control, or approval logic. It protects the application-declared external evidence behind a tool call.

Verification

Before publishing, the release passed:

  • 87 regression tests
  • protected CI across Python 3.10 through 3.13
  • Windows onboarding and package checks
  • wheel and source-distribution validation
  • a clean installation from the public PyPI index
  • an installed Agno example using Agno's real tool chain

In the bounded example, the dependency changes after the decision is created. FreshCtx returns STALE_REASONING, the Agno run is stopped, and the tool body is not executed.

Release: https://github.com/Hyperwise-LLC/freshctx/releases/tag/v0.5.0

Repository: https://github.com/Hyperwise-LLC/freshctx

If you are already using Agno for a consequential tool call, I would value an honest run against one bounded scenario - including anything the integration does not model correctly.

Top comments (1)

Collapse
 
ricart_juncadella_d62f385 profile image
Ricart Juncadella •

The side effect is the part that usually goes wrong, not the answer itself, so putting the check before the tool body is the right boundary. The detail that matters is that it also stops when the dependency cannot be verified under the blocking policy, not only when a change is detected.

A missing check is often the actual failure, especially for deployments or approvals. Keeping it scoped to declared external evidence and leaving run state, transactions and idempotency alone makes the integration much easier to reason about.