"""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