Add pluggable BYOA lookup providers for agent_app

[BlitzBricksterYY-db]

Summary

agent_app currently hardcodes code lookup and web search behavior inside agent_app/agent_server/multi_agent/tools/web_search.py. For Databricks Apps deployment, this makes it difficult for users to bring their own external lookup service (BYOA) in a clean, bundle-configured way.

Proposal

Introduce a small provider abstraction for lookup tools so the app can route through one of several provider kinds configured from agent_app/databricks.yml and loaded at runtime via env vars in the Apps path. Suggested provider kinds:

• builtin for the existing NLM/RxNorm fallbacks
• http for user-supplied REST APIs
• mcp for user-supplied MCP servers

Why this matters

• agent_app is deployed as a Databricks App, and its config already comes from resources.apps.*.config.env in agent_app/databricks.yml
• That deployment model is a good fit for env-driven provider config, not hardcoded URLs in tool code
• A provider registry makes BYOA easier to test, document, and extend without changing the agent flow

Recommendation

Support both HTTP/API and MCP, but make HTTP/API the default BYOA path and MCP an optional advanced provider type. HTTP is simpler operationally for most users, while MCP is useful when a customer already has an MCP server or wants richer tool semantics.

Suggested config shape

Use a single JSON env var such as LOOKUP_PROVIDERS_JSON plus optional secret env vars for credentials. The router can then select providers by capability and code type with fallback ordering.

Acceptance criteria

• Existing behavior remains the default when no BYOA config is supplied
• Users can plug in at least one custom HTTP lookup provider via agent_app/databricks.yml
• MCP providers can be added without changing the core agent workflow
• The design keeps secrets out of YAML and uses env vars or Databricks secret references instead

Notes

The current discover_tools.py already recognizes custom/external MCP server concepts, so this could align with the existing Databricks App / MCP direction while still keeping REST APIs as the easiest integration path.

[BlitzBricksterYY-db]

That means for agent_app specifically (Now we have agent deployed in App instead of model serving endpoint):

• external MCP via UC connections is cleaner than custom MCP app dependencies
• custom MCP apps are possible, but operationally clunkier
• plain HTTP is still the easiest BYOA path

So should you support MCP instead of API URL, or both?

For agent_app: both, but bias the product toward API first.

My recommendation:

• Must-have
  • builtin provider
  • http provider
• Nice-to-have
  • mcp provider
• Do not do
  • MCP-only architecture
  • raw arbitrary URL strings sprinkled through tool code

Best design for this app

Use a provider model like:

• kind: builtin
• kind: http
• kind: mcp

And route by capability:

• code_lookup
• web_search
• later maybe table_lookup, entity_resolver, drug_lookup

Example mental model:

• NDC/ICD/CPT:
  • try customer provider first
  • fall back to builtin NLM provider
• web search:
  • try customer API or MCP tool
  • fall back to DDGS if enabled

Deployment-specific advice for agent_app/databricks.yml

Right now agent_app/databricks.yml hardcodes many values directly under env. If you want real plug-and-play BYOA for other users, I would advise:

• move lookup-related config into a small number of env vars
• ideally parameterize them with bundle variables instead of hardcoding
• keep secrets out of YAML values

For example, even if you stay inside agent_app/databricks.yml, the app should only need something like:

• LOOKUP_PROVIDERS_JSON
• LOOKUP_DEFAULT_PROVIDER
• LOOKUP_HTTP_TIMEOUT_SECONDS
• provider credential env vars

That gives users one place to plug in their provider without editing Python.

Final recommendation

For agent_app, I’d recommend this exact priority order:

1. Refactor web_search.py behind a provider router.
2. Make provider config env-driven from agent_app/databricks.yml.
3. Support BYOA HTTP providers first.
4. Add MCP as an optional provider kind.
5. Prefer external/UC-governed MCP connections over custom MCP app dependencies when possible.

So the short answer is: support both, but for this App deployment architecture, API/HTTP should be the default BYOA path, and MCP should be an advanced extension path.

If you want, I can next outline a concrete agent_app-specific config schema for LOOKUP_PROVIDERS_JSON and show how I’d map it into core/config.py and tools/web_search.py without changing the rest of the agent flow.

[BlitzBricksterYY-db]

Example of config in app's databricks.yml

Go with this as the cleanest agent_app-specific shape.

Minimal env-var schema

Use one global registry var, two route vars, and per-provider vars.

Global

• LOOKUP_PROVIDER_NAMES
  • Comma-separated provider IDs
  • Example: builtin_nlm,builtin_ddgs,customer_icd_api,customer_cpt_mcp

Routes

• LOOKUP_ROUTE_CODE_LOOKUP

  • Semicolon-separated code_type:provider1,provider2
  • Example: NDC:builtin_nlm;ICD10:customer_icd_api,builtin_nlm;CPT:customer_cpt_mcp,builtin_nlm

• LOOKUP_ROUTE_WEB_SEARCH

  • Comma-separated provider order
  • Example: customer_search_http,builtin_ddgs

Provider config

Prefix every provider-specific setting with the provider name.

Examples:

• LOOKUP_PROVIDER_BUILTIN_NLM_KIND=builtin

• LOOKUP_PROVIDER_BUILTIN_NLM_ENABLED=true

• LOOKUP_PROVIDER_BUILTIN_NLM_CAPABILITIES=code_lookup

• LOOKUP_PROVIDER_BUILTIN_NLM_SUPPORTED_CODE_TYPES=NDC,ICD10,CPT,HCPCS

• LOOKUP_PROVIDER_BUILTIN_NLM_TIMEOUT_SECONDS=5

• LOOKUP_PROVIDER_CUSTOMER_ICD_API_KIND=http

• LOOKUP_PROVIDER_CUSTOMER_ICD_API_ENABLED=true

• LOOKUP_PROVIDER_CUSTOMER_ICD_API_CAPABILITIES=code_lookup

• LOOKUP_PROVIDER_CUSTOMER_ICD_API_SUPPORTED_CODE_TYPES=ICD10

• LOOKUP_PROVIDER_CUSTOMER_ICD_API_METHOD=GET

• LOOKUP_PROVIDER_CUSTOMER_ICD_API_URL=https://example.com/icd10/{value}

• LOOKUP_PROVIDER_CUSTOMER_ICD_API_TIMEOUT_SECONDS=5

• LOOKUP_PROVIDER_CUSTOMER_ICD_API_AUTH_TOKEN_ENV=LOOKUP_PROVIDER_CUSTOMER_ICD_API_TOKEN

• LOOKUP_PROVIDER_CUSTOMER_CPT_MCP_KIND=mcp

• LOOKUP_PROVIDER_CUSTOMER_CPT_MCP_ENABLED=true

• LOOKUP_PROVIDER_CUSTOMER_CPT_MCP_CAPABILITIES=code_lookup

• LOOKUP_PROVIDER_CUSTOMER_CPT_MCP_SUPPORTED_CODE_TYPES=CPT

• LOOKUP_PROVIDER_CUSTOMER_CPT_MCP_SERVER_URL=https://mcp.example.com/mcp

• LOOKUP_PROVIDER_CUSTOMER_CPT_MCP_TOOL_NAME=lookup_code

• LOOKUP_PROVIDER_CUSTOMER_CPT_MCP_TIMEOUT_SECONDS=10

• LOOKUP_PROVIDER_CUSTOMER_SEARCH_HTTP_KIND=http

• LOOKUP_PROVIDER_CUSTOMER_SEARCH_HTTP_ENABLED=true

• LOOKUP_PROVIDER_CUSTOMER_SEARCH_HTTP_CAPABILITIES=web_search

• LOOKUP_PROVIDER_CUSTOMER_SEARCH_HTTP_METHOD=GET

• LOOKUP_PROVIDER_CUSTOMER_SEARCH_HTTP_URL=https://search.example.com/search?q={query}&limit={max_results}

Why this is cleaner than JSON

• Easier to read in agent_app/databricks.yml
• Easier to override per target
• Easier to keep secrets separate
• Easier to validate in core/config.py
• Less brittle than huge inline JSON in YAML

Minimal agent_app/databricks.yml addition

This is the deployment-side only part:

- name: LOOKUP_PROVIDER_NAMES
  value: "builtin_nlm,builtin_ddgs,customer_icd_api,customer_cpt_mcp,customer_search_http"
- name: LOOKUP_ROUTE_CODE_LOOKUP
  value: "NDC:builtin_nlm;ICD10:customer_icd_api,builtin_nlm;CPT:customer_cpt_mcp,builtin_nlm;HCPCS:builtin_nlm"
- name: LOOKUP_ROUTE_WEB_SEARCH
  value: "customer_search_http,builtin_ddgs"

- name: LOOKUP_PROVIDER_BUILTIN_NLM_KIND
  value: "builtin"
- name: LOOKUP_PROVIDER_BUILTIN_NLM_ENABLED
  value: "true"
...

Secrets should stay separate:

• LOOKUP_PROVIDER_CUSTOMER_ICD_API_TOKEN
• LOOKUP_PROVIDER_CUSTOMER_SEARCH_API_KEY

core/config.py parsing shape

Keep the agent flow unchanged and add a new config block:

@dataclass
class LookupProviderConfig:
    name: str
    kind: str
    enabled: bool
    capabilities: list[str]
    supported_code_types: list[str]
    timeout_seconds: int = 5
    method: str | None = None
    url: str | None = None
    tool_name: str | None = None
    server_url: str | None = None
    auth_token_env: str | None = None

@dataclass
class LookupRoutingConfig:
    code_lookup: dict[str, list[str]]
    web_search: list[str]

@dataclass
class LookupConfig:
    provider_names: list[str]
    routing: LookupRoutingConfig
    providers: dict[str, LookupProviderConfig]

Parsing logic:

• split comma-separated strings into lists
• parse LOOKUP_ROUTE_CODE_LOOKUP into a dict
• build provider objects by reading LOOKUP_PROVIDER_<NAME>_*
• ignore unknown provider names safely
• fall back to builtin behavior if config is missing

web_search.py integration rule

web_search.py should only ask the router:

• router.lookup_code("ICD10", value)
• router.search(query, max_results)

No agent graph changes. No changes to enrich_codes() call sites. Only internals.

My recommendation

If you want the simplest durable version, make the first implementation support only:

• builtin
• http

Then add mcp as a third provider kind once the router is stable.

If you want, I can next write the exact parsing grammar for:

• LOOKUP_ROUTE_CODE_LOOKUP
• LOOKUP_PROVIDER_<NAME>_*

so you can implement it with almost no ambiguity.