Files
cp1-agents/docs/source-material/agent-shapes/subagent-pattern/app/business_logic.py
Jonathan Boniface 416c66ced4
All checks were successful
check agents / check (push) Successful in 10s
Add CP1 Discovery agents in both patterns
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>
2026-10-29 18:25:57 +00:00

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