22
33 python doctor.py # laptop + .env + Agent Engine + Kafka + Schema Registry + MCP
44 python doctor.py --offline # laptop only (run this before the event)
5+ python doctor.py --agent-only # laptop + Agent Engine (for ork local / L1)
56
67Every failed check prints the fix.
78"""
@@ -40,9 +41,10 @@ def check_python(version: tuple) -> Check:
4041
4142def check_orca_base_url (url : str ) -> Check :
4243 parts = urlsplit (url .strip ())
43- if parts .scheme != "https" or not parts .netloc :
44- return Check ("ORCA_BASE_URL" , False , url , "Use the full https:// registry endpoint from your team card." )
45- root = f"https://{ parts .netloc }
44+ local_http = parts .scheme == "http" and parts .hostname in ("localhost" , "127.0.0.1" , "::1" )
45+ if not parts .netloc or (parts .scheme != "https" and not local_http ):
46+ return Check ("ORCA_BASE_URL" , False , url , "Use the https:// registry endpoint from your team card, or http://127.0.0.1:8080 for ork local." )
47+ root = f"{ parts .scheme } { parts .netloc }
4648 if parts .path .rstrip ("/" ):
4749 return Check ("ORCA_BASE_URL" , False , url , f"Use the host root only: ORCA_BASE_URL={ root } )
4850 return Check ("ORCA_BASE_URL" , True , root )
@@ -98,9 +100,11 @@ def kafka_hint(error: str) -> str:
98100# ---------------------------------------------------------------- probes --
99101
100102
101- def check_packages () -> list [Check ]:
103+ def check_packages (agent_only : bool = False ) -> list [Check ]:
102104 checks = []
103105 for module , package in PACKAGES .items ():
106+ if agent_only and module == "confluent_kafka" :
107+ continue
104108 found = importlib .util .find_spec (module ) is not None
105109 checks .append (Check (f"package { package } , found , "" , "" if found else "Run: pip install -r requirements.txt" ))
106110 return checks
@@ -123,7 +127,7 @@ def probe_orca(config: Any) -> Check:
123127 orca_client (config ).agents .list (limit = 1 )
124128 except APIStatusError as err :
125129 if err .status_code in (401 , 403 ):
126- fix = "The Agent Engine rejected SN_API_KEY. A key created before its rolebinding must be re-created: ask a facilitator ."
130+ fix = "The Agent Engine rejected the key. For ork local use its generated workspace key as ORCA_API_KEY; for a team card check SN_API_KEY and its rolebinding ."
127131 elif err .status_code == 404 :
128132 fix = "ORCA_BASE_URL is not an Agent Engine registry: copy the registry endpoint from your team card."
129133 else :
@@ -151,7 +155,8 @@ def probe_kafka(config: Any) -> Check:
151155 )
152156 topic_name = config ["LOGIN_TOPIC" ]
153157 try :
154- topic = admin .list_topics (topic = topic_name , timeout = 15 ).topics .get (topic_name )
158+ # Listing all existing topics avoids metadata requests that can auto-create a missing topic.
159+ topic = admin .list_topics (timeout = 15 ).topics .get (topic_name )
155160 except KafkaException as err :
156161 reason = errors [0 ] if errors else str (err )
157162 return Check ("Kafka" , False , reason , kafka_hint (reason ))
@@ -219,15 +224,18 @@ def probe_mcp(config: Any) -> Check:
219224# ------------------------------------------------------------------ main --
220225
221226
222- def run_checks (offline : bool ) -> list [Check ]:
223- checks = [check_python (sys .version_info ), * check_packages (), * check_cli_tools ()]
227+ def run_checks (offline : bool , agent_only : bool = False ) -> list [Check ]:
228+ checks = [check_python (sys .version_info ), * check_packages (agent_only ), * check_cli_tools ()]
224229 if offline or not all (check .ok for check in checks ):
225230 return checks
226231
227232 from common import load_config
228233
229234 config = load_config ([])
230- missing = [name for name in CARD if name not in config .values ]
235+ required = ("ORCA_BASE_URL" , "ORCA_MODEL" ) if agent_only else CARD
236+ missing = [name for name in required if name not in config .values ]
237+ if agent_only and not any (name in config .values for name in ("ORCA_API_KEY" , "SN_API_KEY" )):
238+ missing .append ("ORCA_API_KEY or SN_API_KEY" )
231239 if missing :
232240 fix = "Copy .env.example to .env in the repo root and paste your team card."
233241 return [* checks , Check ("team card (.env)" , False , "missing " + ", " .join (missing ), fix )]
@@ -237,14 +245,16 @@ def run_checks(offline: bool) -> list[Check]:
237245 checks .append (base_url )
238246 if base_url .ok :
239247 checks .append (probe_orca (config ))
248+ if agent_only :
249+ return checks
240250 checks .append (probe_kafka (config ))
241251 checks += probe_schema_registry (config )
242252 checks .append (probe_mcp (config ))
243253 return checks
244254
245255
246256def main () -> int :
247- checks = run_checks (offline = "--offline" in sys .argv [1 :])
257+ checks = run_checks (offline = "--offline" in sys .argv [1 :], agent_only = "--agent-only" in sys . argv [ 1 :] )
248258 for check in checks :
249259 print (f"{ 'PASS' if check .ok else 'FAIL' } { check .name :<32} { check .detail } )
250260 if not check .ok and check .fix :
0 commit comments