All checks were successful
check agents / check (push) Successful in 10s
ALZ-F01 Discovery as a sub-agent orchestrator (sub-agents/) and as eight individual declarative agents (individual-agents/), with their KAB workflow exports. Shared check, render and import scripts, the alz-discovery-sample MCP server, the crucible-kab-dev deploy profile, deployment docs, platform issue reports and the source material. Agent steps time out at 20 minutes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
194 lines
8.3 KiB
Python
194 lines
8.3 KiB
Python
"""Where your business logic goes.
|
|
|
|
All four functions below are wired up already and do nothing yet. Fill in the
|
|
one you need — the wiring is already correct, so you only edit this file.
|
|
|
|
request ─▶ pre_process(payload) ONCE per request, on the parsed JSON
|
|
│
|
|
▼
|
|
before_model() once per MODEL CALL
|
|
│
|
|
▼
|
|
the model ◀── tools ──┐
|
|
│ │
|
|
▼ │
|
|
after_model() ────────┘ once per model call
|
|
│
|
|
▼
|
|
post_process(result) ONCE per request, on the final JSON
|
|
│
|
|
▼
|
|
response
|
|
|
|
Which pair you want comes down to one question: does the work belong to the
|
|
*request*, or to each *model turn*?
|
|
|
|
`pre_process` and `post_process` belong to the request. They receive a parsed
|
|
dict — the shape your input and output schemas describe — and run exactly once,
|
|
however many times the model is called in between. Normalising an identifier,
|
|
enriching from a lookup, stamping a field onto the result: all request work.
|
|
|
|
`before_model` and `after_model` belong to the turn. They receive the
|
|
runtime's ModelCall -- the same on every framework -- and run on every model
|
|
call, which in a tool loop is several times.
|
|
|
|
Putting request work in the per-call pair is the usual bug. A lookup in
|
|
`before_model` runs four times in a four-step tool loop, and you pay for it
|
|
four times; the same lookup in `pre_process` runs once.
|
|
|
|
Use these when the work is *deterministic* — something that should happen on
|
|
every request, whether or not the model decides it is a good idea. Reading a
|
|
config file, redacting an identifier, enforcing a house style, validating the
|
|
shape of a reply.
|
|
|
|
Use a **tool** instead (`functions:` in agent.yaml) when the model should decide
|
|
whether and when to do the thing, and can use the result to choose what to do
|
|
next. Tools are what create the agent loop; these hooks do not.
|
|
|
|
Two things worth knowing before you start:
|
|
|
|
* The loop bounds in kubernetes/configmap.yaml are enforced by the runtime
|
|
alongside these hooks. Nothing you return here switches them off.
|
|
|
|
* Anything you read at runtime must be COPYed in the Dockerfile. It works
|
|
locally without that, because ./run-local.sh bind-mounts the project into
|
|
the container — but there is no such mount in Kubernetes, and the file will
|
|
simply not be there. This is the most common way an agent passes locally
|
|
and fails on deploy.
|
|
|
|
You do not set up logging, tracing or correlation headers here. The runtime has
|
|
already wrapped those around this agent.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from typing import Any, Optional
|
|
|
|
import structlog
|
|
|
|
from kyndryl_agent_runtime import agent_manifest
|
|
|
|
# The agent's logger. Use this one.
|
|
#
|
|
# Every agent on the platform logs through structlog, so every agent's output
|
|
# is parsed the same way, searchable by the same fields, and shipped by the
|
|
# same pipeline. An agent that reaches for `print()` or its own `logging`
|
|
# config is the one nobody can query when it misbehaves at 2am.
|
|
#
|
|
# Bound with the agent's name so a line is attributable once the logs of forty
|
|
# agents are in one place. Add your own permanent context the same way:
|
|
#
|
|
# logger = logger.bind(region=os.getenv("REGION", "unknown"))
|
|
#
|
|
# House style, and it is worth following:
|
|
#
|
|
# * an event name, then key=value -- `logger.info("rate_applied",
|
|
# currency="EUR", rate=1.09)`, not a sentence with the values glued in.
|
|
# The first is searchable; the second is prose that happens to contain
|
|
# numbers.
|
|
# * INFO for what happened, DEBUG for the data it happened to. A claim, a
|
|
# ticket, a patient note -- these belong at DEBUG, because a log that is
|
|
# unsafe to keep is a log somebody turns off, taking everything else with
|
|
# it.
|
|
# * never a secret, a token or a full payment detail, at any level. There is
|
|
# no log level that makes an API key safe to store.
|
|
# * no need to log that a request arrived, that pre_process ran, or what the
|
|
# model replied -- the runtime already does all of that around you. Log
|
|
# what is yours: the decision you made and why.
|
|
logger = structlog.get_logger(__name__).bind(
|
|
agent=agent_manifest().name or "agent",
|
|
)
|
|
|
|
|
|
def before_model(call: Any) -> None:
|
|
"""Runs immediately before each call to the model, on any framework.
|
|
|
|
`call` is the runtime's ModelCall, the same object on Google ADK, LangChain,
|
|
LangGraph, Strands and Microsoft Agent Framework, so this file runs
|
|
unchanged on all of them. Add to the system instructions for this one call:
|
|
|
|
call.add_instruction("The customer's region is EMEA.")
|
|
|
|
Prefer the system instructions over the user's message: anything placed
|
|
inside a user turn is markedly easier for a crafted prompt to talk the
|
|
model out of. `call.native` holds the framework's own arguments, for what
|
|
add_instruction does not cover. The return value is ignored.
|
|
|
|
Called once per model call, so this runs several times in a tool loop, not
|
|
once per request. Keep it cheap; cache anything you read from disk.
|
|
"""
|
|
return None
|
|
|
|
|
|
def after_model(call: Any) -> None:
|
|
"""Runs immediately after each reply from the model, on any framework.
|
|
|
|
`call.reply_text` is the reply's text -- empty for a reply that only calls
|
|
a tool or loads a skill. Good uses: record a domain metric, check the
|
|
shape of a structured reply. The return value is ignored; to change the
|
|
final answer use post_process, which runs once on it.
|
|
"""
|
|
return None
|
|
|
|
|
|
def pre_process(payload: dict) -> Optional[dict]:
|
|
"""Runs once per request, on the incoming payload, before any model call.
|
|
|
|
`payload` is the request parsed as JSON. When this agent declares an input
|
|
schema it has already been validated against it, so you can read the fields
|
|
you declared without defensive checks — a payload that did not match never
|
|
reaches here; the caller received a structured error naming the JSON path
|
|
that was wrong.
|
|
|
|
Return a modified dict to change what the model is asked, or None to leave
|
|
the payload alone. Returning a dict that is equal to what you were given is
|
|
the same as returning None.
|
|
|
|
def pre_process(payload):
|
|
payload["account_id"] = payload["account_id"].strip().upper()
|
|
return payload
|
|
|
|
An agent with no input schema, or one called with prose rather than JSON,
|
|
does not call this at all — there is no payload to hand you.
|
|
|
|
Raising here fails the request. That is the right move for something you
|
|
genuinely cannot proceed without; prefer returning a corrected payload for
|
|
anything you can repair.
|
|
"""
|
|
# An example of the house style, left here on purpose: delete it or keep it,
|
|
# but log like it. An event name and fields, at a level that matches what
|
|
# the line carries.
|
|
#
|
|
# logger.info("claim_received", category=payload.get("category"))
|
|
# logger.debug("claim_payload", payload=payload)
|
|
#
|
|
# The first is safe anywhere and answers "what kind of work is this agent
|
|
# doing?". The second answers "what exactly did it get?" and is DEBUG
|
|
# because it is the caller's data.
|
|
logger.debug("pre_process_input", fields=sorted(payload))
|
|
|
|
return None
|
|
|
|
|
|
def post_process(result: dict) -> Optional[dict]:
|
|
"""Runs once per request, on the final reply, after the model is done.
|
|
|
|
`result` is the model's reply parsed as JSON. Return a modified dict to
|
|
change what the caller receives, or None to leave it as it is.
|
|
|
|
def post_process(result):
|
|
result["reviewed_at"] = datetime.now(timezone.utc).isoformat()
|
|
return result
|
|
|
|
Two things to know. First, the output contract is checked *after* this
|
|
runs, on what you return -- so the caller never receives a reply that
|
|
breaks it. A dict that does not conform sends the model round once more,
|
|
and if it still fails the caller gets an `output_contract_violation`. The
|
|
runtime logs `post_process_broke_output_contract` with the offending paths
|
|
when it was your edit that broke it, which is the fastest way to find it.
|
|
|
|
Second, a reply that is not JSON never reaches here. If your agent answers
|
|
in prose, this hook simply does not run.
|
|
"""
|
|
return None
|