tPjUdZddlZddlZddlZddlmZmZddlmZddl m Z m Z m Z m Z ddlmZmZmZmZmZddlmZmZddlZddlmZdd lmZdd lmZdd lmZm Z m!Z!m"Z"dd l#m$Z$m%Z%m&Z&dd l'm(Z(m)Z)m*Z*m+Z+m,Z,m-Z-ddl.m/Z/ddl0m1Z1ddl2m3Z3ddl4m5Z5ddl6m7Z7ddl8m9Z9m:Z:m;Z;mZ>m?Z?ddl@mAZAddlBmCZCmDZDdedeEfdZFde9dzddfdZGddde9dzdeEdedeEdzdeHeEeIff dZJeZKe eLd<d ee=ddfd!ZMd ee=deNe=fd"ZOd#e!ddfd$ZPeQejjd%d&ZTe eLd'<eQejjd(d)ZUGd*d+e d,-ZVd.e=deVfd/ZWGd0d1e ZXd2eYd3eEd4eEdefd5ZZd6eEd ee=d7eYd#e!de[e=d8ff d9Z\eKjd:d;gee1geNe=<ed,d=>de(ee1fd?ed@e]d6e eEdzedAdBCfd7e eYedAdDdEFfd#e!f dGZ^ddHl_m`Z`ddIl_maZbeKjd:d;gee1ge=<ee1fd?e:ded#e!fdJZdeKjdKd;gee1ge=<ee1fdeEd#e!fdLZeeKjdKd;gee1ge=<ee1fdeEd?e:ded#e!fdMZgeKjdKd;gee1ge=<ee1fdeEd?e?ded#e!fdNZieKjdKdOgee1gPee1fdeEd#e!fdQZkeKjdRd;gee1ge<<ee1fdeEd#e!fdSZleKjdTd;gee1ge<<ee1fd?e>d#e!fdUZmeKjdVdWgee1geD<ddddddAdXdee1f dYeEdzdZeEdzd[eEdzd\eEdzd]eEdzd^eYd_eYd`eEdzd#e!fdaZny)bz Agent endpoints for registering + discovering agents via LiteLLM. Follows the A2A Spec. 1. Register an agent via POST `/v1/agents` 2. Discover agents via GET `/v1/agents` 3. Get specific agent via GET `/v1/agents/{agent_id}` N)MappingSequence)MappingProxyType) AnnotatedFinal TypedDict assert_never) APIRouterDepends HTTPExceptionQueryRequest)ReadOnlyRequired)verbose_proxy_logger)_get_masked_values)get_async_httpx_client)CommonProxyErrorsLitellmUserRolesUserAPIKeyAuthuser_api_key_has_admin_view)SUPPORTED_A2A_PROTOCOL_VERSIONSmerge_agent_cardnormalize_protocol_version)DEFAULT_AGENT_SEARCH_TOP_KAgentSearchEmbeddingFailedAgentSearchHitsAgentSearchNotConfiguredglobal_agent_search_index search_agents)accessible_agentsuser_api_key_auth)check_feature_access_for_user)get_daily_activity)get_custom_url) AgentCard AgentConfigAgentKeySummaryAgentMakePublicResponse AgentResponseMakeAgentsPublicRequestPatchAgentRequest)httpxSpecialProvider)DailySpendMetadataSpendAnalyticsPaginatedResponse http_requestreturncBtt|jdS)zGReturn the proxy's public base URL, preferring PROXY_BASE_URL when set.N)route)r&strbase_url)r1s l/home/oem/CyberBrain26-unified/.venv/lib/python3.12/site-packages/litellm/proxy/agent_endpoints/endpoints.py_proxy_base_urlr8As #l334D AA upstream_cardc |r|jdnd}|3t|'tdd|ddjtdyy) zAReject an agent card pinning an unsupported A2A protocol version.protocolVersionNzUnsupported protocolVersion 'z'. Supported versions: z, . status_codedetail)getrr joinr)r:versions r7_validate_protocol_versionrEFsg=J]&&'89PTG9'BJ/y9''+yy1P'Q&RRSU   Kr9 agent_nameagent_idrGct|}t||r|jdnd}t||d|||xs|S)zGApply the LiteLLM-fronting merge to ``upstream_card`` for ``agent_id``.nameNz/a2a/) proxy_urlproxy_base_urlrJ)r8rErBr)r:rHr1rG proxy_base card_names r7_build_merged_agent_cardrOSsV( 5J}- 5B}((0tI LhZ0!  $*  r9routeragentsc$ Kddlm t fd|D}|sy|jjj dd|iid{}i}|D]W}|j |jgjt|j|j|jY|D]Q} j|jDcgc]}|j|xsd D]}| } }}| xsd|_Sy7cc}}ww) a#Attach each agent's virtual keys, derived from the key table's agent_id foreign key. Mirrors how spend is joined into the agent response so the UI never has to cross-reference a full key dump client-side. Only non-secret fields are exposed (alias, masked key_name, hashed token).rglobal_agent_registryc3bK|]&}j|jD]}|(ywN ids_for_agentrH.0agentalias_idrTs r7 z)_attach_keys_to_agents..ts;5J5X5XY^YgYg5h)1,/NrHinwhere)token key_aliaskey_name),litellm.proxy.agent_endpoints.agent_registryrTtupledblitellm_verificationtoken find_many setdefaultrHappendr)rbrcrdrXrBkeys) rQ prisma_client agent_idskey_rows keys_by_agentrowr[r\ key_summary matched_keysrTs @r7_attach_keys_to_agentsrums/ S$I ),,FFPPD),-QH>@M   r299 ii--   *2??O ,00:@b     ")T * s%A DDBD#D 7D Dcg}|D]c}|jd}d|_d|_d|_|jrt |jdd|_|j |e|S)z Return copies of the given agents with sensitive configuration fields redacted. The original objects are not modified. T)deepN)unmasked_lengthnumber_of_asterisks) model_copystatic_headers extra_headersrmlitellm_paramsrrl)rQredactedr[copys r7_redact_sensitive_agent_fieldsrs|,.H T*"!   "4## !$%#D    Or9user_api_key_dictcv|jtjk7rtddd|jiy)z Raises HTTP 403 if the caller does not have permission to create, update, or delete agents. Only PROXY_ADMIN users are allowed to perform these write operations. errorzBOnly proxy admins can create, update, or delete agents. Your role=r?N) user_roler PROXY_ADMINr )rs r7"_check_agent_management_permissionrsI ""&6&B&BB]^o^y^y]z{  Cr9"LITELLM_AGENT_HEALTH_CHECK_TIMEOUTz5.0"AGENT_HEALTH_CHECK_TIMEOUT_SECONDS)LITELLM_AGENT_HEALTH_CHECK_GATHER_TIMEOUTz30.0c8eZdZUeeed<eeed<eed<y)_AgentHealthResultrHhealthyrN)__name__ __module__ __qualname__rr5__annotations__boolrer9r7rrssm d^ Jr9rF)totalr[cK|jxsijd}|s|jddS ttj dt i}|j|d{}|jdk\r|jdd |jd S|jddS7?#t$r#}|jdt|d cYd}~Sd}~wwxYww) z Perform a GET request against the agent's URL and return the health result. Returns a dict with ``agent_id``, ``healthy`` (bool), and an optional ``error`` message. urlT)rHrtimeout) llm_providerparamsNFzHTTP rHrr) agent_card_paramsrBrHrr.AgentHealthCheckrr@ Exceptionr5)r[rclientresponseexcs r7_check_agent_url_healthrs))/R44U;C !NNt<< .->>AB !' 3/   3 &!NN  !5!5 67  "NNt<<0  X   sR1C5B+)B)*/B+CB+(C)B++ C4C C CCCc.eZdZUeeed<eeed<y)_AgentSearchErrorDetailrmessageN)rrrrr5rrer9r7rrs C= c]r9rr@rrc&||d}t||S)N)rrr?)r )r@rrrAs r7_agent_search_errorrs7<-QF [ @@r9querytop_k.c <Kddlm}t||||tjt |d{}|xt dx\}td|DSxtdx\}tdd|tdx\}tdd | t|y7iw) Nr) llm_router)rrQrrPembedding_modelindexrrec3~K|]5}|jjtd|ji7yw) search_score)updateN)r[r{rscore)rZhits r7r]z(_rank_agents_by_query..s5thk--5E~WZW`W`Fa5b-cts;=r=agent_search_not_configurediagent_search_unavailable) litellm.proxy.proxy_serverrr litellmagent_search_embedding_modelrrrgrrrr )rrQrrroutcomehitsreasons r7_rank_agents_by_queryrs6(<<'+G  "_ "tostt t# - % -%c+H&Q Q. ' /%c+EvN N0   !#s.BBA*Bz /v1/agentsz[beta] A2A Agents)tags dependenciesresponse_modelzWhen true, performs a GET request to each agent's URL. Agents with reachable URLs (HTTP status < 500) and agents without a URL are returned; unreachable agents are filtered out.) descriptionrequest health_checkzDescribe the task in natural language to rank the agents you can reach by semantic similarity over their name, description, and skills. Each result carries a search_score. Requires litellm_settings.agent_search_embedding_model.) min_lengthrdz:With query: the maximum number of ranked agents to return.)gelerc Kt|dd{ddlm t|d{}ddlm}|t fd|D}|rt|jdd|ii d{}|D cic]} | j| jc} |D]B} t fd j| jD} | s3t| | _ Dt||d{|D]o} | ji| _tj duxr9j| jj#tj  | jd <q|j$t&j(k(xs'|j$t&j(j*k(} | s t-|}|r|D cgc]$} | j.xsij1d s#| &} } |D cgc]$} | j.xsij1d r#| &}} t3j4t3j6| D cgc] } t9| c} t: d{}|Dchc] }|ds |d}}| D cgc]} | j|vs| c} |z}||StC||||d{S777Qcc} w7cc} wcc} wcc} w7x#t2j<$r@t?j@dt:| D cgc]} | jdddncc} w}} YwxYwcc}wcc} w7#tD$rtF$r-}t?jHd|tEddd|id}~wwxYww)a Example usage: ``` curl -X GET "http://localhost:4000/v1/agents" -H "Content-Type: application/json" -H "Authorization: Bearer your-key" ``` Pass `?health_check=true` to filter out agents whose URL is unreachable: ``` curl -X GET "http://localhost:4000/v1/agents?health_check=true" -H "Content-Type: application/json" -H "Authorization: Bearer your-key" ``` Pass `?query=` to get the best matching agents ranked by semantic similarity: ``` curl -X GET "http://localhost:4000/v1/agents?query=translate+a+PDF+document&top_k=5" -H "Content-Type: application/json" -H "Authorization: Bearer your-key" ``` Returns: List[AgentResponse] rQNrrSrnc3bK|]&}j|jD]}|(ywrVrWrYs r7r]zget_agents..@s=% 5 C CENN S%%%r^rHr_r`c30K|] }|vr|ywrVre)rZr\ spend_maps r7r]zget_agents..Ks&+$#y0"(++s is_publicr)rz4Agent health check gather timed out after %s secondsFzHealth check timed outrrzClitellm.proxy.agent_endpoints.get_agents(): Exception occurred - %srrzInternal server error: r?)%r$rfrTr!rrnrg agents_tablerjrHspendrXsumrur~rpublic_agent_groups isdisjointrrrvaluerrrBasynciowait_forgatherr)AGENT_HEALTH_CHECK_GATHER_TIMEOUT_SECONDS TimeoutErrorrwarningrr r exception)rrrrrreturned_agentsrnro db_agentsar[matched_spendsis_adminagents_with_urlagents_without_urlhealth_resultsresult healthy_idserTrs @@r7 get_agentsrsd ((98 DDDRJ^9JK\9]3] =  $$%,% I )5m)D)N)N%i'89*O*$ BK#KAAJJ$7#K ,:E%*+(=(K(KENN([+&N &&).&9 :-_mLLL% E##+')$070K0KSW0W1%33ENNCNNwOjOjk]E  -   ' '+;+G+G G Q **.>.J.J.P.PP <_MO 9H%wUMdMdMjhjLoLopuLve%wO%w5D!wEUMdMdMjhjLoLopuLv%!w !w ELEUEUNNQ`$a%[4\]]^s.NJ> NMKAM3K4M<K7M!M3K 4CM$K*K.M4$KKM "K K K %K&K *M. L69L6ML;L; M'N(M9M:M=NMMM MK 1L3L)(L30M2L33MN(M<<NN)rrScKt|dd{ddlm}t|| t dd |j xsd}t j|jd  }| t d d |jd d |jd}|}d}|Cttj}t||||jd } i|d| i}t j||||d{} | j} | j} t j | t#j$d| | | S7@7O#t&$r#} t#j(d| | | Yd} ~ | Sd} ~ wwxYw#t$rt&$r1}t#j*d|t dt|d}~wwxYww)a Create a new agent Example Request: ```bash curl -X POST "http://localhost:4000/v1/agents" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "agent_name": "my-custom-agent", "agent_card_params": { "protocolVersion": "1.0", "name": "Hello World Agent", "description": "Just a hello world agent", "url": "http://localhost:9999/", "version": "1.0.0", "defaultInputModes": ["text"], "defaultOutputModes": ["text"], "capabilities": { "streaming": true }, "skills": [ { "id": "hello_world", "name": "Returns hello world", "description": "just returns hello world", "tags": ["hello world"], "examples": ["hi", "hello world"] } ] }, "litellm_params": { "make_public": true } }' ``` rQNrrrPrisma client not initializedr?unknownrGrFr=Agent with name z already existsrrHr1rG)r[rn created_byrH agent_configz5Successfully registered agent '%s' (ID: %s) in memoryz4Failed to register agent '%s' (ID: %s) in memory: %szError adding agent to db: %s)r$rrnrr user_idAGENT_REGISTRYget_agent_by_namerBr5uuiduuid4rOadd_agent_to_dbrGrHregister_agentrinforrr)rr1rrnrexisting_agentr:agent_to_create new_agent_id merged_cardrrGrH reg_errorrs r7 create_agentrs` ((98 DDD8&'894STT9<-55B !/ @ @GKKXdLe f  %)'++l*C)DOT  '{{+>? '.#'  $tzz|,L!9%)";;|4 "K LK*={KO,<<!'!!   #--  //   ) )v > % %&]_iks t  yER   ( (F T\^g      <&&'EqICF;;8F=G >FFG ,GG  G z/v1/agents/{agent_id}c\Kt|dd{t|s4ddlm}|j ||d{}|st dd|d dd lm}| t d d  tj| }|pt|jd|iddid{}|~|j}|j |jj|d<t!di|}n8t|jd|id{}||j"|_|t dd|d t%|g|d{|j&t(j*k(xs'|j&t(j*j,k(} | st/|gd}|S77r7 #t$r |jj|d<YwxYw77#t $rt$r1} t1j2d| t d t5|  d} ~ wwxYww)z Get a specific agent by ID Example Request: ```bash curl -X GET "http://localhost:4000/v1/agents/123e4567-e89b-12d3-a456-426614174000" \ -H "Authorization: Bearer " ``` rQNr)AgentRequestHandler)rHr#rzAgent 'zC' is not allowed for your key/team. Contact proxy admin for access.r?rrrrHrHobject_permissionT)raincluder`Agent with ID not foundzError getting agent from db: %sre)r$r;litellm.proxy.agent_endpoints.auth.agent_permission_handlerris_agent_allowedr rrnrget_agent_by_idr find_unique model_dumprrdictr+rrurrrrrrrr5) rHrr is_allowedrnr[ agent_row agent_dictdb_rowrrs r7rrs\& ((98 DDD &'8 9 /??ev?ww   *mn  94STT'<..A =%1-%@%L%L!8,,d3&M& I$$-$8$8$: ..:]:C:U:U:`:`:b #67&3 3#/}"="I"IQ[]ePf"I"ggF!$ll =C. R\8]^ ^$eWm<<<  ' '+;+G+G G Q **.>.J.J.P.PP 2E7;A>E kEx %]:C:U:U:Z:Z:\ #67] h =  <&&'H!LCF;;" \ -H "Content-Type: application/json" \ -d '{ "agent_name": "updated-agent", "agent_card_params": { "protocolVersion": "1.0", "name": "Updated Agent", "description": "Updated description", "url": "http://localhost:9999/", "version": "1.1.0", "defaultInputModes": ["text"], "defaultOutputModes": ["text"], "capabilities": { "streaming": true }, "skills": [] }, "litellm_params": { "make_public": false } }' ``` rQNrrrr?rHr`rrrrrrGrrHr[rn updated_byrFr2Successfully updated agent '%s' (ID: %s) in memoryError updating agent: %s)r$rrnrr rdb_not_connected_errorrrrr rrBrOrupdate_agent_in_dbderegister_agentrrrrrr5) rHrr1rrnrrr:agent_to_updaterrrs r7 update_agentrUsR ((98 DDD8&'894E4\4\4b4bcc1<+M:FFjZbMcFdd  %!.1N  !C. R\8]^ ^.55B  '{{+>? '.  $!9!)";;|4 "K LK*={KO,??!'!    ''>3E3El3ST%%6:!! @.BTBTUaBbdl  kEe4 "  <&&'A1ECF;;" \ -H "Content-Type: application/json" \ -d '{ "agent_name": "updated-agent", "agent_card_params": { "protocolVersion": "1.0", "name": "Updated Agent", "description": "Updated description", "url": "http://localhost:9999/", "version": "1.1.0", "defaultInputModes": ["text"], "defaultOutputModes": ["text"], "capabilities": { "streaming": true }, "skills": [] }, "litellm_params": { "make_public": false } }' ``` rQNrrrr?rHr`rrrrrrGrrrFrrr)r$rrnrr rrrrrr rrBrOrpatch_agent_in_dbrrrrrrr5) rHrr1rrnrr patch_payloadr:rrrs r7 patch_agentrsR ((98 DDD8&'894E4\4\4b4bcc2<+M:FFjZbMcFdd  %!.1N  !C. R\8]^ ^.55B ,3 &{{+>?  $!9!)";;|4 "K JwI(;[IM,>>'!    ''>3E3El3ST%%6:!! @.BTBTUaBbdl  mEe6 "  <&&'A1ECF;;" ``` Example Response: ```json { "message": "Agent 123e4567-e89b-12d3-a456-426614174000 deleted successfully" } ``` rQNrrrrr?rHr`rrz not found in DB.)rHrnrGrFrzAgent z deleted successfullyzError deleting agent: %s)r$rrnrr rrr r5objectrdelete_agent_from_dbrrBrrr)rHrrnrrs r7 delete_agentr!"s,2 ((98 DDD8&'894STT<+M:FFjZbMcFdd  %!#v+.~>N  !C. Rc8de e118S`aaa''>3E3El3STVH:-BCDD-Ee b  <&&'A1ECF;;" \ -H "Content-Type: application/json" ``` Example Response: ```json { "agent_id": "123e4567-e89b-12d3-a456-426614174000", "agent_name": "my-custom-agent", "litellm_params": { "make_public": true }, "agent_card_params": {...}, "created_at": "2025-11-15T10:30:00Z", "updated_at": "2025-11-15T10:35:00Z", "created_by": "user123", "updated_by": "user123" } ``` rrNrr?rS proxy_configrr<  <  & &*:*F*F F[\m\w\w[xy /..A =&}5AAU]H^A__E %;(8(8(:;}#nXJV`>:+5577 V +v6H/I/Q)+F% &Y>Y[l[t[t B#*#>#>+33  C`$8 :  <&&'FJCF;;H/H0C H=H>9H7H8AHIHHHI ,II  Iz/v1/agents/make_publiccKddlm}|%tdtjj  ddl}ddlm}ddlm }|jd{}|jtjk7rtdd d |ji|jg|_|jD]k}|j | }|t#|j%d |i d{}|t'di|j)}|\tdd|d|j|_d|vs|di|d<|j|dd<|j+|d{t-j.d|j|j0d|j|j0dS7[77N#t$rt2$r1} t-j4d| tdt7| d} ~ wwxYww)a( Make multiple agents publicly discoverable Example Request: ```bash curl -X POST "http://localhost:4000/v1/agents/make_public" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "agent_ids": ["123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426614174001"] }' ``` Example Response: ```json { "agent_id": "123e4567-e89b-12d3-a456-426614174000", "agent_name": "my-custom-agent", "litellm_params": { "make_public": true }, "agent_card_params": {...}, "created_at": "2025-11-15T10:30:00Z", "updated_at": "2025-11-15T10:35:00Z", "created_by": "user123", "updated_by": "user123" } ``` rrNrr?rSr#rrr%rrHr`rrrr&rr'r)r*r+r,re)rrnr rrrrrfrTr$r-rrrrrorrrr+rr.rr/rrrr5) rrrnrrr$r0rHr[rs r7make_agents_publicr3s$N94E4\4\4b4bcc9<  <+5577  & &*:*F*F F[\m\w\w[xy   & & .*,G ')) gH2N22HEE}*=9EEZYaLbEcc$)?E,<,<,>?E='C.QYPZZd@eff g'.&7&7# V +v6H/I/Q)+F% &Y>Y[l[t[t B#*#>#>+33  O8"d :  <&&'FJCF;;r?/litellm.proxy.management_endpoints.common_utilsr@resolve_agent_accesslistrrrjrHsetr0r/rGr%)ror5r6r7r8r9r:r;rrnagent_ids_listexclude_agent_ids_listrr>r?r@where_conditionpermitted_agent_idsallowed_agent_ids owned_recordsrpermitted_agent_id_setaid agent_recordsr[agent_metadatas r7get_agent_daily_activityrd+sx( ((98 DDD8.EEKKL  .7Y__S)DN/3AR!2!8!8!=X\  U02O  1 2)+(<-F-FG2W2,M@M*M!1::*M'*M + ,/0C,D "-;]csF\?\c]N]!"56N2+ #(),-!"'(./*+236734 !" &'+T.-A&B #!-m!=Bu'7'788>N>$#," ,1    aEFb ,+N^8^> sHG)BH%G,&AH=G/>HG1H. G68G6litellm.types.proxy.management_endpoints.common_daily_activityr/r0r5r8rEr rrOrPrrurXrrfloatenvironrBrrrrrintrrgrrrrfrrTrpostrrputrpatchrdeleter!r1r3rdrer9r7rs -"<<EE01II  ZBOW.@ B'BcB  i$.>  4  $" t#  d   #v+ . *-)@*TX*B ] # -.  .  T  -2"**..Aegl2m,n"En,1"**..Alnt2u,v)%    Di ASAAsA}A " " /"8;"P^" =# "2  +,- &   H  #(/0A(B#z^ z^z^  d  ~    z^   s(de g z^"&#z^  z^~   +,-  )00A(Bl< l<l<&l<  l<^  +,-  )00A(BG<G<%G<  G