tdfs4ds.agentops¶
Package the tdfs4ds consumer agent for Teradata AI Studio's AgentOps runtime.
AgentOps deploys an agent from a zip holding agent.py, customer_agent.py,
config.yaml and requirements.txt, plus the platform's own
agent_runtime/. Its tutorials build a stateless-per-call agent;
:func:tdfs4ds.consumer_agent is the opposite — module-level globals, one
process-wide teradataml context, and a graph singleton whose MemorySaver is
the conversation memory. The generated package reconciles the two.
The design principle is that the package is derived from a working session
rather than hand-written. By the time a user runs this they have already proved
their configuration by asking the agent questions; the split between what is
safe to commit and what must be injected at deploy time is then computed from
:mod:tdfs4ds.config's own credential classification, not guessed.
Three entry points, in the order they are used::
# One call: validate -> preflight -> zip -> register -> deploy -> verify
tdfs4ds.deploy_to_agentops('./teradata_agent', database='MY_STORE',
token=tok, auth='jwt', progress=print)
# Or the individual steps
tdfs4ds.check_agent_deployment(database='MY_STORE') # before
print(tdfs4ds.generate_agentops_package(database='MY_STORE'))
tdfs4ds.write_agentops_package('./teradata_agent', database='MY_STORE')
tdfs4ds.check_deployed_agent(agent_url, token=tok) # after
module-attribute
¶
__all__ = ['deploy_to_agentops', 'check_agent_deployment', 'generate_agentops_package', 'write_agentops_package', 'deployment_payload', 'check_deployed_agent', 'analyze_pod_log', 'format_insights', 'AgentOpsClient', 'remove_agent', 'agent_endpoint', 'find_agent']
Minimal client for the endpoints a deployment needs.
Parameters¶
base_url : str, optional
Defaults to TD_AGENTOPS_BASE_URL, then the in-cluster service URL.
token : str, optional
JWT bearer token. Defaults to TDFS4DS_AGENTOPS_TOKEN. In an AI
Studio notebook this is the user_token produced by %gen_token.
Upload the zip and register an agent definition. Returns its id.
Poll until the definition leaves creating. Returns its status.
POST the deployment payload. Returns the full response body.
The payload is sent verbatim; see the module docstring on
extra_forbidden.
Poll the deployment until it settles. Returns the last body.
Emits current_step transitions rather than every poll, so a long
build reads as building -> pushing -> deploying instead of forty
identical lines.
DELETE /agents/{id}: removes the deployment (pod, route, service).
DELETE /agent_definitions/{id}: removes the registry entry.
Pod logs. Never raises — a missing log must not mask the real error.
deployment_payload(agent_definition_id, runtime_config, *, deployment_name=None, environment='dev', docker_image=None)
Build the POST /agents payload with the constraints already applied.
The result is sent to the API verbatim, so it carries only fields the API defines — no generation timestamp or other bookkeeping that a strict endpoint would reject.
The tutorial's payload is sized for a toy agent. Three fields differ here, and each is load-bearing rather than a preference:
resources
512Mi does not hold teradataml + langchain + pandas + networkx.
replicas: 1
Conversation memory is an in-process MemorySaver; a second replica
answers with no history.
enable_memory: False
The platform's PostgreSQL checkpointer cannot be injected into the
tdfs4ds graph, so enabling it would provision a database nothing reads.
generate_agentops_package(*, mcp_enabled=False, backend=None, auth='service', database=None, database_view=None, databases_readonly=None, data_domain=None, td_host=None)
Render the deployment package.
Model, embedding and Vector Store settings are read from the running session — you have proved those work by asking the agent questions, and reproducing them is the point. The feature store is stated, not inherited: it is a deployment target, and a pod that silently picks up whatever the session had is impossible to review at the call site.
Nothing is written and nothing is sent anywhere.
Parameters¶
mcp_enabled : bool, default False
Baked into the generated agent as the mcp_enabled argument to
:func:tdfs4ds.consumer_agent. Off by default; True is
Enterprise-edition only and adds per-caller MCP authentication.
backend : str, optional
Vector store backend to classify against. Defaults to the running
tdfs4ds.VECTOR_STORE_BACKEND.
auth : {'service', 'jwt'}, default 'service'
Credential model for the generated agent.
database, database_view, data_domain : str, optional
The feature store the deployed agent serves. Each falls back to the
running session when omitted; :func:tdfs4ds.deploy_to_agentops
requires database so a deployment always names its target.
databases_readonly : list of str, optional
Additional stores attached read-only (cross-store federation).
td_host : str, optional
The database host the POD connects to, when it differs from the
session's TDFS4DS_TD_HOST (a pod that cannot resolve the name gets
its address). Only runtime_config changes; the session is untouched.
Returns¶
dict
{"files": {name: text}, "runtime_config": {...}, "dropped": [...],
"missing_runtime": [...], "version": str, "auth": str, "store": {...}}.
``runtime_config`` goes in the deployment payload, **not** on disk.
``store`` reports the resolved feature store, so "which database will
this read?" is answerable before anything is deployed.
write_agentops_package(dest=None, *, mcp_enabled=False, backend=None, auth='service', database=None, database_view=None, databases_readonly=None, data_domain=None, agent_runtime='auto', make_zip=True, td_host=None)
Write the package into dest and (by default) build the deployable zip.
Parameters¶
dest : str, optional
The scaffolded agent directory — the one holding agent_runtime/.
Defaults to {tdfs4ds.AGENTOPS_PACKAGE_DIR}. Created when absent,
with a warning: a package with no agent_runtime/ registers fine and
then fails at pod start, so the gap is worth naming early.
make_zip : bool, default True
Also build <dest>.zip next to the directory — the artifact uploaded
to POST /agent_definitions.
Returns¶
dict
The :func:generate_agentops_package result plus "dest",
"zip_path" and "written" (the file names written).
check_agent_deployment(*, live=True, display=True, dest=None, auth='service', mcp=False, agent_runtime='auto', database=None, database_view=None, databases_readonly=None, data_domain=None)
Validate that this session can be packaged and deployed to AgentOps.
Runs :func:tdfs4ds.check_configuration's checks first — a configuration
broken here cannot become correct in a container — then the deployment
checks: the config split, package installability, the platform runtime
library, structured output, the vector backend, the business dictionary and
the connection environment.
Parameters¶
live : bool, default True
Make the outbound calls. False inspects configuration only.
display : bool, default True
Print the aligned summary, with a fix hint under anything not passing.
dest : str, optional
The scaffolded agent directory, so agent_runtime/ can be verified.
auth : {'service', 'jwt'}, default 'service'
Which credential model the deployment will use. 'jwt' expects the
caller's token per request, so only TDFS4DS_TD_HOST is required at
deploy time. Must match the auth= passed to
:func:generate_agentops_package.
Returns¶
dict
{"ok", "version", "live", "checks": [...]}, the same shape as
:func:tdfs4ds.check_configuration.
Notes¶
Never raises, and never returns or prints a secret — variable names only.
Examples¶
import tdfs4ds tdfs4ds.check_agent_deployment() # doctest: +SKIP tdfs4ds.check_agent_deployment(live=False) # doctest: +SKIP
Exercise a deployed AgentOps agent and report what works.
Sends three turns: an opening question, a follow-up on the same
session_id, and the same follow-up on a fresh one. Between them they
establish that the pod is reachable, answers, answers from the feature
store, remembers within a session and does not leak across sessions.
Parameters¶
agent_url : str
The agent_url from GET /agents/{agent_id}. A trailing
/invoke is added when absent.
token : str, optional
JWT bearer token. Defaults to TDFS4DS_TD_PASSWORD-independent
environment lookup of TDFS4DS_AGENTOPS_TOKEN; in AI Studio pass the
notebook's user_token.
live : bool, default True
`False makes no HTTP call — every check reports as skipped. For
wiring tests.
display : bool, default True
Print the aligned summary.
Returns¶
dict
{"ok", "version", "live", "checks": [...]}, the same shape as
:func:tdfs4ds.check_configuration.
Notes¶
Never raises, and never prints the token.
Examples¶
tdfs4ds.check_deployed_agent(agent_url, token=user_token) # doctest: +SKIP
deploy_to_agentops(dest=None, *, database=None, databases_readonly=None, database_view=None, data_domain=None, token=None, base_url=None, auth='service', mcp=False, name=None, description=None, dry_run=False, timeout=1800, require_published=True, agent_runtime='auto', verify=True, startup_timeout=300, progress=None, pod_host='auto')
Package, deploy and verify the consumer agent on AgentOps.
Parameters¶
dest : str, optional
The scaffolded agent directory holding the platform's agent_runtime/.
Defaults to tdfs4ds.AGENTOPS_PACKAGE_DIR.
database : str
Required. The feature store the deployed agent serves. Stated rather
than inherited, so the pod's store is visible at the call site.
databases_readonly : list of str, optional
Stores attached read-only. Each is validated before deploying.
database_view, data_domain : str, optional
View database and default data domain for the deployed agent.
token : str, optional
JWT for the AgentOps API. In AI Studio, the user_token from
%gen_token.
auth : {'service', 'jwt'}
Credential model baked into the generated agent.
**Prefer ``'jwt'`` where the environment allows it** — and note the
reasoning is the opposite of the notebook case, where a token that
expires in two hours makes a ``.env`` stop working:
* the token arrives **per request** from the caller, so expiry
self-heals instead of accumulating;
* the pod connects **as the caller**, so database permissions and
audit reflect the real user rather than one shared account;
* no durable database password sits in ``runtime_config``, which is
rendered **in clear** in the deployment UI — verified against a live
deployment. Its guarantee is "not committed to source control", not
secrecy.
``'service'`` is nevertheless the default, because ``'jwt'`` is
**conditional on something outside tdfs4ds**: the platform's
``auth_context.token`` has to be accepted by *Vantage* as a JWT logon
(``logmech='JWT'``, ``logdata='token=...'``). A token minted for a
platform API is not automatically a database credential — this package
has watched the MCP gateway accept a platform bearer and the database
then refuse the logon it attempted with it (Error 8017). A pod cannot
mint a token of its own, so where the platform's token is not a valid
Vantage JWT, ``'jwt'`` is simply not deployable and ``'service'`` with
a real account is the way in.
Test it before deploying, from the notebook, with the token the pod
will be handed::
tdml.create_context(host=..., logmech='JWT',
logdata='token=' + os.environ['OAUTH_ACCESS_TOKEN'])
A session there means ``auth='jwt'`` is viable; a refusal means it is
not, whatever else is configured.
mcp : bool, default False
Enable MCP tools (Enterprise edition only). Off is the recommended first
deployment: it removes Enterprise auth and the 132-tool context budget
from the run, so a failure is unambiguously about the agent.
dry_run : bool, default False
Validate, preflight and build the zip, then stop and return the payload
without touching the API.
require_published : bool, default True
Refuse when the running version is not on PyPI. Set False when a private
index carries it.
verify : bool, default True
Run the smoke test once the deployment is active. False returns as
soon as it is deployed, leaving verification to a later
:func:~tdfs4ds.agentops.smoke.check_deployed_agent call on
report["agent_url"] — useful when the pod is slow to warm, or when
the caller holding a token is not the one running the deploy.
startup_timeout : int, default 300
Seconds to wait for the pod's tdfs4ds startup block to appear in the log
before drawing conclusions from it. active is the platform's verdict
on the pod, which it reaches before tdfs4ds has finished importing, so
reading the log immediately finds nothing on a healthy deployment. The
wait ends early as soon as the block appears or an error signature
does. Set 0 to read once and move on.
progress : callable, optional
Called with a status line per step. None (default) shows a progress
bar over the stages instead; either way every stage is logged, a failed
one at ERROR with its cause and fix.
pod_host : str, 'auto' or None, default 'auto'
The database host the pod connects to. 'auto': on AI Studio, where
a pod cannot resolve the database name the notebook uses, the name is
resolved here (as is, then with cop1..cop3) and the pod gets the
address; elsewhere the session's TDFS4DS_TD_HOST is used unchanged.
A string is used as given; None keeps the session's value. The
session itself is never changed.
Returns¶
dict
{"ok", "verified", "stages", "store", "agent_definition_id",
"agent_id", "agent_url", "insights", "smoke", "payload"}. Stages use
the same {name, status, detail, hint} shape as every other tdfs4ds
report.
``ok`` is the **deployment's** verdict: the pod is active and has a URL.
``verified`` is the **smoke test's** — ``True``/``False``, or ``None``
when it did not run. They are separate because a check that depends on
pod warmth failing does not mean the deployment failed, and reporting it
as one flag sent a user to debug a deployment that was fine.
Raises¶
ValueError
database not given.
RuntimeError
The running version is not published and require_published is set.
Return findings for a pod log.
Parameters¶
text : str
Raw log text, as returned by GET /agents/{id}/logs.
max_excerpt : int
Per-finding excerpt cap. The excerpt is the first matching line, which
for a stack trace is the one naming the cause rather than the innermost
frame.
Returns¶
list of dict
{"name", "severity", "insight", "excerpt"}, errors first then
warnings then info, in table order within each severity. Empty when
nothing matched — which is itself a finding the caller should report as
"no known signature", never as "healthy".
Render findings as aligned plain text. ASCII only.
A deployment report is read on whatever console the notebook happens to have, and is often saved to a file: the same reason the rest of tdfs4ds keeps generated artifacts ASCII.
remove_agent(agent, *, delete_definition=True, dry_run=False, others=False, token=None, base_url=None, timeout=300, progress=None, client=None)
Remove a deployed agent from AgentOps.
Parameters¶
agent : str
The deployment's UUID, a prefix of it (the short id the Playground shows,
e.g. '85f752e'), or its deployment name.
delete_definition : bool, default True
Also delete the registered agent definition, unless another deployment
that is not terminated still uses it (then it is kept and the report says
which).
dry_run : bool, default False
Resolve and report what would be removed; send nothing.
others : bool, default False
GET /agents lists the whole workspace, so a name can belong to another
user's agent. By default a deployment whose created_by is not the
token's user is refused; True removes it anyway (if the platform allows).
token, base_url
As for :class:AgentOpsClient (in an AI Studio notebook, the token from
%gen_token).
timeout : int, default 300
Seconds to wait for the platform to report the deployment gone.
progress : callable, optional
Called with a status line per step.
Returns¶
dict
{"ok", "dry_run", "agent_id", "name", "definition_id", "status_before",
"status_after", "definition", "steps", "error"}. Never raises for an
API refusal: the full response is in error and logged at ERROR.
The URL of a deployed agent, found by name, id or short id.
Parameters¶
agent : str
Deployment name (e.g. 'tdfs4ds-propensity-demo'), UUID, or the short
id the Playground shows.
invoke : bool, default False
False: the agent's base URL, what deploy_to_agentops reports as
agent_url and check_deployed_agent takes. True: the /invoke
route a client POSTs a question to.
token, base_url
As for :class:AgentOpsClient (in an AI Studio notebook, %gen_token).
Raises¶
LookupError No deployment, several, or the deployment is not active (no URL to call).
The one deployment agent names, as returned by GET /agents.
Raises LookupError when nothing or several deployments match.