1.7. Agent Configuration#

pycsamt.api.agents holds AGENT_CONFIG, the process-local singleton that every agent in pycsamt.agents reads its LLM provider, model, API key, pricing table, and spending cap from – configure it once, and every agent constructed afterwards inherits the setting automatically.

The full guide – provider setup, credential resolution order, the .env.local fallback, temporary overrides, budget caps, custom pricing, and a troubleshooting table – already lives at Agent And LLM Configuration. This page exists only to place AGENT_CONFIG in the same family lineup as every other pycsamt.api singleton (see API configuration) and give a fast quick-reference; read the linked page before configuring a real provider.

One thing to notice up front: unlike PYCSAMT_STYLE or PYCSAMT_INTERP, AGENT_CONFIG has no dotted-path configure(section__attr=...) method. Its settings – provider, key, model, rates, budget – are not a nested style tree, so configure() takes plain keyword arguments instead:

>>> from pycsamt.api.agents import AGENT_CONFIG, configure_agents, reset_agents

>>> _ = reset_agents()
>>> _ = configure_agents(
...     provider="claude",
...     api_key="sk-ant-demo-0000",
...     model="claude-sonnet-4-6",
... )
>>> print(AGENT_CONFIG)
AgentConfig(provider='claude', model='claude-sonnet-4-6', key='…0000')

AGENT_CONFIG.info() gives the same state as a plain dict, with the key masked to its last four characters – safe to log or print without leaking a credential:

>>> info = AGENT_CONFIG.info()
>>> info["provider"], info["model"], info["api_key_masked"], info["key_source"]
('claude', 'claude-sonnet-4-6', '…0000', 'explicit')

A session budget cap is one call, checked before every LLM request an agent makes – see Agent And LLM Configuration for the BudgetExceededError it raises once the cap is reached:

>>> AGENT_CONFIG.set_budget(usd=1.5)
AgentConfig(provider='claude', model='claude-sonnet-4-6', key='…0000', budget=$1.50 (spent=$0.0000))
>>> AGENT_CONFIG.spent_usd, AGENT_CONFIG.remaining_usd
(0.0, 1.5)

>>> _ = reset_agents()

offline() is narrower than it first sounds: it only suppresses the environment-variable fallback for the current thread, so a stray ANTHROPIC_API_KEY in the shell can’t cause an unintended LLM call from a script or test run. An explicitly stored key (from configure() or set_key()) is unaffected and still resolves inside the block:

>>> import os
>>> os.environ["ANTHROPIC_API_KEY"] = "sk-ant-env-fallback-demo"
>>> AGENT_CONFIG.switch("claude")
AgentConfig(provider='claude', model='claude-sonnet-4-6', key='…demo')
>>> AGENT_CONFIG.api_key is not None
True

>>> with AGENT_CONFIG.offline():
...     print(AGENT_CONFIG.api_key)
None
>>> AGENT_CONFIG.api_key is not None
True

>>> del os.environ["ANTHROPIC_API_KEY"]
>>> _ = reset_agents()

1.7.1. Next Steps#

  • Agent And LLM Configuration for the full guide: the quick decision table, credential resolution order, .env.local, using(), custom pricing with set_rate(), and troubleshooting.

  • Agent Catalogue for what each concrete agent class does once it has a provider to call.

  • API configuration for how the agents family fits alongside every other pycsamt.api configuration family.

On this page