[FEATURE] Expose execution lifecycle hooks and metadata for agent reliability tooling

[ishita-0301]

Expose execution lifecycle hooks and metadata for agent reliability tooling

Long running agents and workflows can encounter issues such as repeated retries, circular execution paths, stalled progress, and other forms of non productive execution.

Today, many of these behaviors are difficult to observe or intercept without embedding reliability logic directly into application code.

Proposal

Expose lightweight execution lifecycle hooks and metadata around agent and tool execution.

Examples could include

BeforeToolCall(...)
AfterToolCall(...)
OnRetry(...)
OnFailure(...)
OnLoopDetected(...)

Along with metadata such as

ExecutionID
ParentExecutionID
ToolName
AttemptCount
StepCount
Duration
CorrelationID

Benefits

This would make it possible to build reliability features as separate components rather than coupling them to business logic.

Potential use cases include

• Loop detection
• Retry policies
• Circuit breakers
• Execution auditing
• Progress tracking
• Resource monitoring
• Custom recovery workflows

The goal would not be to prescribe a particular implementation, but to expose enough information for the community to experiment with different approaches.

I have seen similar ideas emerging in agent runtimes where reliability is treated as a separate concern from orchestration. Some projects are beginning to build runtime policies around execution patterns such as repeated tool calls, excessive retries, and stalled workflows. Having standardized lifecycle events in Go Micro would make it much easier to integrate or experiment with those kinds of reliability layers.
One example is https://github.com/FailproofAI/failproofai, which focuses on runtime detection of loops and execution failures rather than orchestration itself.

Go Micro already provides strong primitives for communication and orchestration. Exposing execution lifecycle events feels like a natural next step for supporting more autonomous and long running agent workloads.

[asim]

From Claude:

Thanks for the thoughtful write-up — this lines up closely with how we've been thinking about reliability, and a good chunk of it already exists in v6, with the last pieces just added.

The seam: AgentWrapTool. Rather than a fan of separate callbacks (BeforeToolCall, OnRetry, …), Go Micro exposes one composable wrapper around tool execution — the tool-side analogue of client.CallWrapper/server.HandlerWrapper:

func reliability(next ai.ToolHandler) ai.ToolHandler {
    return func(ctx context.Context, call ai.ToolCall) ai.ToolResult {
        start := time.Now()
        res := next(ctx, call)            // "before" is above, "after" is here
        // ... record timing, inspect result, retry by calling next again ...
        return res
    }
}
micro.NewAgent("worker", micro.AgentWrapTool(reliability))

A wrapper is a superset of before/after/retry/failure hooks: "before" is code above next, "after" is below it, retry is calling next again, and failure interception is inspecting what it returns. It composes (multiple wrappers, outermost-first) and runs outside the built-in guardrails, so it sees every call and its outcome — including refusals.

Mapping your proposal:

Requested	In v6
BeforeToolCall / AfterToolCall / OnRetry / OnFailure	AgentWrapTool (one seam)
OnLoopDetected	a refusal now carries a structured reason — res.Refused == ai.RefusedLoop (also RefusedMaxSteps, RefusedApproval)
CorrelationID / ExecutionID / ParentExecutionID	ai.RunInfoFrom(ctx) → RunID, ParentID, Agent; plus per-call call.ID
ToolName / Duration	call.Name; time.Since(start) around next
StepCount / AttemptCount	counted by the wrapper itself (it sees every call / every retry)
Loop detection / retry / circuit breaker as separate components	exactly the intent — built as wrappers + the MaxSteps/LoopLimit/ApproveTool guardrails

The structured refusal reason and ai.RunInfo shipped just now in response to this issue — they were the genuine gaps. Everything else was already there.

Docs: the Agent Guardrails guide (see Tool-execution middleware → Reliability metadata) and the runnable examples/agent-wrap-tool.

We deliberately stopped short of adding the literal On* callback surface, since it would duplicate the wrapper. If there's a reliability case the wrapper + this metadata genuinely can't express, that'd be great to hear — happy to keep iterating.

---

Generated by Claude Code

[ishita-0301]

Thanks for the detailed explanation. This makes a lot of sense.
I was initially thinking in terms of explicit lifecycle callbacks because that's how a lot of agent runtimes expose reliability and observability integrations. Looking at it through the AgentWrapTool abstraction, I can see how the wrapper model is strictly more flexible while avoiding API surface duplication.
The new RunInfo metadata and structured refusal reasons were actually the pieces I was most interested in. Being able to distinguish loop limits, approval requirements, and other execution outcomes programmatically opens the door to much richer reliability tooling.
What I find particularly interesting is that this creates a clean separation between orchestration and runtime reliability. Features like loop detection, retry policies, execution auditing, progress tracking, and custom recovery strategies can now be implemented externally without requiring changes to the agent implementation itself.
I'll spend some time experimenting with wrappers and the new metadata. It feels like the primitives are now in place for building higher level reliability layers on top of Go Micro.