Projeto do Agent Contas ORACLE
This commit is contained in:
86
agent_framework_oci/docs/01_billing_agent_invoice_policy.pdf
Normal file
86
agent_framework_oci/docs/01_billing_agent_invoice_policy.pdf
Normal file
@@ -0,0 +1,86 @@
|
||||
%PDF-1.4
|
||||
%“Œ‹ž ReportLab Generated PDF document (opensource)
|
||||
1 0 obj
|
||||
<<
|
||||
/F1 2 0 R /F2 3 0 R /F3 4 0 R /F4 5 0 R
|
||||
>>
|
||||
endobj
|
||||
2 0 obj
|
||||
<<
|
||||
/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
3 0 obj
|
||||
<<
|
||||
/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
4 0 obj
|
||||
<<
|
||||
/BaseFont /ZapfDingbats /Name /F3 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
5 0 obj
|
||||
<<
|
||||
/BaseFont /Courier /Encoding /WinAnsiEncoding /Name /F4 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
6 0 obj
|
||||
<<
|
||||
/Contents 10 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 9 0 R /Resources <<
|
||||
/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
|
||||
>> /Rotate 0 /Trans <<
|
||||
|
||||
>>
|
||||
/Type /Page
|
||||
>>
|
||||
endobj
|
||||
7 0 obj
|
||||
<<
|
||||
/PageMode /UseNone /Pages 9 0 R /Type /Catalog
|
||||
>>
|
||||
endobj
|
||||
8 0 obj
|
||||
<<
|
||||
/Author (\(anonymous\)) /CreationDate (D:20260606193923+00'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260606193923+00'00') /Producer (ReportLab PDF Library - \(opensource\))
|
||||
/Subject (\(unspecified\)) /Title (\(anonymous\)) /Trapped /False
|
||||
>>
|
||||
endobj
|
||||
9 0 obj
|
||||
<<
|
||||
/Count 1 /Kids [ 6 0 R ] /Type /Pages
|
||||
>>
|
||||
endobj
|
||||
10 0 obj
|
||||
<<
|
||||
/Filter [ /ASCII85Decode /FlateDecode ] /Length 2092
|
||||
>>
|
||||
stream
|
||||
Gb!#\gMYb*&:Ml+b[\);<Db\Jqbe]qVT<4t9j7^J$ttL+g$%FY;A/HMmgLMbZK#0&qiD#i+]4[GSs_TOBEg*g1%UeK!&kR9J'3@f0UVqLS,amc_5GDoc\lZeVM2sF]),7dZ6Wn`rN55S!pcqCOV9$I_S?[%Q\FH2-3[X\cUD!SXl>%ZY1+]orUC@enFcW6BO362!Ek[G"[;Ms9Rae<*VgWmA\R4#mWd4E4eE*iK/^MPm.Q^clf&b:Tn@>3\7]&ic15Jf/d,_RrN-<r97-@@'`Q`n/;Re@T4Dnd,P,0+o6)Jqq6r9Q&_rXIPtVA:=1M"+2P/=Yq^/u3!IF*GJA)JSKdL"Y"aG=MW+De/n1oWbX1>0[cSn/Fj"lS57t%\anQNC1X2#DOo8VYL6>E""q`es!Y;2g5]G)7-.L#K3["1?h![$F0GaS'o;.,bY'HO]a+g&nUb7a1KY0mKGU<RELOPRpQC3$#m0#`b=WmM!jGBjKn!OBqf$bDq4N+^:m.&J33cj$-fTm0ilB.ka>kBLkup)m%\!@gk(dm)La7\!(u0-3L=]1s>S$]J0h9#0fL#*c!s9L2O:FhQ=l2!4`JqOS@(n7/@j3]#]$+3ZDH4XY2OFKY9HqM2t2'LM#UAc?#XJh,&D<TSWaO)O/SDcg5Tag!WCB"W!q^Ol-L-(f6&S8,h9&F&=.^L'E5'kf_IU+F]M?Lh&8hrU9_2Gsb3I[QRCguO$7+cDlNBsLpbPipD,U#9Q.F=e*Niu:(i0;S<tmRFA>\m^-"T01$QpVi#7VSLN<DAR?-&F'@F-Rr6h'kJ%]!rHqncm'ajP154%ZDLEKCFj)=9-8<[s!RgGET+jm3!`CC[_BM*^2U^rSh10]CDO^d*57gEGBi$$\F$Gk)a(C[9GA!RnB*?da`%9am"2u\b."NV0Q'fTbPalml,u8U#ihlH_qbi^j!,';nX8+^#mDl>W.Jmo,*(^+L-s'[O']+ffrcK8FBoV`hmUa"A3,j)R3\=Pn7n)h!7_E6='rdA<@BT3dbf?0Gp>d@,6kqqGsXlC\)o@=e]V-r6mc]^T1PSSNN$7637:H(cS-#!4#!pk$3c0>`/14GiD<\30H3`")<H;+1,h6d@>gJ@XS,DKJ[2<?75AO#mIZWhLR+5uBNcVs8CZ@T8iNF-rArZq+@&B'3S69%m`Na%^^lVFJ*Vg3gj"6al1Nsn%X(7F\+]M1_VNFDBpaqH8'K2aC(MQ899IAb9J,auI5)CMR#D9,F-*C/\=ou0XZs7NE$uleVtIs&=Ik%RjM(j<#>tD+379s+DaBYbS#K/JS-jC-cb0OblUV'd$GKbS:Xp0o>3`1O"iVU/$Rc4qImVNqK!'*Xd3NJ'&4eH6e*oKW3S<8+N75:e\U5T=i(.3$W])U(ZT'WKYCZ;^[fDqBr;:`>r%*-$-RHE6k"hdY5$,V.YcO(jjZdpBfA&KX9'"u+$ee49A_3s+:MOL]%Vqm_T7%4)e/t@Tdd_j8s*.!#<D"7VQl#OH@Rd?_D$^>[;m%r>01:Y^LO)s,=XBl@7qirC,uq:ONP==t,t]P,Z<#$t6NsOEr,j5:UoQ<gcK5s6g:2,\f8HZNZ[k[<Q>^A5l+5J>5-'O'dTShS)IncPb;.>39MiMAQc*K=$7q/Fj)<-U\NZ16Zr)]ig7/@B-j21@c:!HM9H#^X,]^qF!8HDn'^ERaKOE#o3)3og>WRPp]JFF1BoKl<Pe4f&7fU>9"up=drj,a_b>7M6XG*c5OSj"i@^\?99H$GbmHBQ-P&b#J=^0rD6+9i$p(r9X4SKSp`k=ml6B$8Y2`Xr&Ye6X^W&I)R;joX\i;hZ\nM3?$;hppV]!C<$6:Q;QUi'>C*TNeAnL1Him"41k4!h4l6.ef*Ph_?*emi+nYKfZL#.@;[`@8-Z(V5B9`Uhk@Bk;OJ<MEMli35`SUWhGX3IV+tUL6[a#..nX`@l"`4\WSin6LgjmHqs^>M+CP67M9Y4u.E8"IhV9llA>d!@D8o!LW'Rl.ll/9GcG^/#nRoTIaF/e_k3;XMaQBS:\4hU`)_mb;aq2jnb<PHi17FdN(^:CbVG\G_;$Oa?>M<mhVfDjUH^'J;\mX^qjJq~>endstream
|
||||
endobj
|
||||
xref
|
||||
0 11
|
||||
0000000000 65535 f
|
||||
0000000061 00000 n
|
||||
0000000122 00000 n
|
||||
0000000229 00000 n
|
||||
0000000341 00000 n
|
||||
0000000424 00000 n
|
||||
0000000529 00000 n
|
||||
0000000733 00000 n
|
||||
0000000801 00000 n
|
||||
0000001081 00000 n
|
||||
0000001140 00000 n
|
||||
trailer
|
||||
<<
|
||||
/ID
|
||||
[<dbfb1252f0166701838e06181766ca6b><dbfb1252f0166701838e06181766ca6b>]
|
||||
% ReportLab generated PDF document -- digest (opensource)
|
||||
|
||||
/Info 8 0 R
|
||||
/Root 7 0 R
|
||||
/Size 11
|
||||
>>
|
||||
startxref
|
||||
3324
|
||||
%%EOF
|
||||
@@ -0,0 +1,86 @@
|
||||
%PDF-1.4
|
||||
%“Œ‹ž ReportLab Generated PDF document (opensource)
|
||||
1 0 obj
|
||||
<<
|
||||
/F1 2 0 R /F2 3 0 R /F3 4 0 R /F4 5 0 R
|
||||
>>
|
||||
endobj
|
||||
2 0 obj
|
||||
<<
|
||||
/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
3 0 obj
|
||||
<<
|
||||
/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
4 0 obj
|
||||
<<
|
||||
/BaseFont /ZapfDingbats /Name /F3 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
5 0 obj
|
||||
<<
|
||||
/BaseFont /Courier /Encoding /WinAnsiEncoding /Name /F4 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
6 0 obj
|
||||
<<
|
||||
/Contents 10 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 9 0 R /Resources <<
|
||||
/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
|
||||
>> /Rotate 0 /Trans <<
|
||||
|
||||
>>
|
||||
/Type /Page
|
||||
>>
|
||||
endobj
|
||||
7 0 obj
|
||||
<<
|
||||
/PageMode /UseNone /Pages 9 0 R /Type /Catalog
|
||||
>>
|
||||
endobj
|
||||
8 0 obj
|
||||
<<
|
||||
/Author (\(anonymous\)) /CreationDate (D:20260606193924+00'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260606193924+00'00') /Producer (ReportLab PDF Library - \(opensource\))
|
||||
/Subject (\(unspecified\)) /Title (\(anonymous\)) /Trapped /False
|
||||
>>
|
||||
endobj
|
||||
9 0 obj
|
||||
<<
|
||||
/Count 1 /Kids [ 6 0 R ] /Type /Pages
|
||||
>>
|
||||
endobj
|
||||
10 0 obj
|
||||
<<
|
||||
/Filter [ /ASCII85Decode /FlateDecode ] /Length 1844
|
||||
>>
|
||||
stream
|
||||
Gb!#\D/\/e&H88.EVnl5M(2El",7uTR\F#:Uof2r1`2(Tfgqi18P/jKGGHLRG5\01bE=!677t5QF*GrO$iq/oM>9h<J.GS'Im\`_R-$Y]a+rn2I%4O@\EIR74cq^45OJY,8O<Kj=#JS_OFHjFFM`\X"?bR]8Iu%Z/R`Z_k>_UCMO"*BW^jSro.sXffBZ4/ZZ92faCO"jprooqr=7;#g7Gu+nJpi)dIs=/CsIT6DgXk.LK?grq[j!_K75/WB:O.ioX;pqpj0XJ2\`3kpIl#11j5V7O(4]PAh^bo)-:si&afA&cLED='6#IBT!$Ln&,ogN^Mho^miWo(*V9O@8RS8-CBl6]X]il9"041jR%!UNfR+XV"#e%V3bae2%dhIQbQ<t:`%uS7$W.Fc]Dq1$n1Nb/QrcD&>UjD&*,N,QebM(<3539K5'p]%,Hij-53$HVZur-_\-?ZO/9\:g4BD$`i#0O=YHQnd]MX8FZ,/N2gR(%Oocjg;CSu]HGkqYgYIOT>hhshj4kGNX9^O?nTHVD6D*_^4`[$GES\A^eW=&FW&QG_C%%tU8(JJ:']fm>p&l?Vm8U0[g#2"6F4?Wc8kuk(E.oA(0Jk!lapl!7QqXe+>[$Jk7D@9/5foftlPF&Kk_<i[8B9uH<6DQpY2+j`M!uZTO7@Q&X":4:`jk<e-aqAtN_b-khm-5liq.UtsZt9OX9*^A/B*cD[pmu'[+2.f=Tb3Cp1cQ\`kJ\0M5aG["7!@6<Jbdk&jGF/Vm]lXJrdDP#@N,%C.alW8l_b,G#4Ob)Fh+Jf]IVp0R;hP5GAGje4D-g^J!hFb-h)#@n7$_GmtM,o(Ma*@\d@@d*K&S!qPLaojUe0labJ4;57f1i*XIobFm*^-CEJk7JC'LWBQ?XmY,bkV;H?(4T/[1<P3mX*KVr^HP,*uq("6g;F:p/[M*s3k)H_gW;NK#0RA#uj)\h:gX48Nghf*V<48^C1Y\MHrMZ7@8D&,P$BiVPY1%LeL.)`&s;tQ``a*Jo`!a1'6P#+B#-"K@4Zmf%;.p3>l,%n'\XW;r#63=:6I_)X"Ajr03KduaTCWo9&qQTn"dIn5lNV9'CDdNpUI/GZ1n9/-*'ZTFa/,e7Y7K+>]%]7jOO:P`aS5hHur'f+0%1d<.EF.l6&k]T!BX"Id#7aD&@LW,NOO2B6!0ZH_X$P1%hBOk-n]^8AC\gHDgEK.,bcIrhbTbSr_8g;cs$qH+2"LtBktBo+,#m_qI>H6(@@_&.*6h1"'Xj?C$nu#_(4`[&GVq/ohUt0C"(5]d5a6&?HF`H)%kP8K2*tcQT4JAOCCG<L*g\-*3NWtl-0\o8ga;2G`WjtRd3d1(SRRA^ksfDcg1.`nMu*"B_bl7E!ob^#PsoL0\XO<Fp:5DZKkOLXBdd,RA!'0.6[AhmXH*Udgfe9?H!SMr?fRCtDrum.Q/XHA0#M1f&XKj)\<l'#Z#9CbD;DK!7>sAa;6U9f!m4-mjpbC]*9kqlAAj9tn6EU"37cF?G0WZG2i<%9]p]V)#?TR@7`:/D,R3/V#Ik<5N*.Zc1#T#mehPZ%\Qb#gO56b6[NX]cq9[]edQ4Hck;T^T!s)ld[ASG;Iehe(2j4Ge*Lf2g3cJ@hRK0_&d<-]VdHG*-DB#ehU0^.J\W&>8R8$U9!af]!n,<R/&aI$<dd/4)qG7[s-aM$;PF2.,n@;ufKhpS+QeGcYRS3\2'pM;V5]+%4;d4YDru6HHJ:tXjk0<VZ$qRT8FK_sC*E*s%WfNad`W5#4Kgs>\iXA(?\eli%@#(2>,E!^P].Ljr2dPX=`)>>%#a+m6Ztd#cY=@_[-VM&X1WWE@K52eRK1SH^!ecL3!4^n+Hi~>endstream
|
||||
endobj
|
||||
xref
|
||||
0 11
|
||||
0000000000 65535 f
|
||||
0000000061 00000 n
|
||||
0000000122 00000 n
|
||||
0000000229 00000 n
|
||||
0000000341 00000 n
|
||||
0000000424 00000 n
|
||||
0000000529 00000 n
|
||||
0000000733 00000 n
|
||||
0000000801 00000 n
|
||||
0000001081 00000 n
|
||||
0000001140 00000 n
|
||||
trailer
|
||||
<<
|
||||
/ID
|
||||
[<de6ad45fd71682cb736d5c1e4032a87e><de6ad45fd71682cb736d5c1e4032a87e>]
|
||||
% ReportLab generated PDF document -- digest (opensource)
|
||||
|
||||
/Info 8 0 R
|
||||
/Root 7 0 R
|
||||
/Size 11
|
||||
>>
|
||||
startxref
|
||||
3076
|
||||
%%EOF
|
||||
80
agent_framework_oci/docs/03_product_agent_catalog_policy.pdf
Normal file
80
agent_framework_oci/docs/03_product_agent_catalog_policy.pdf
Normal file
@@ -0,0 +1,80 @@
|
||||
%PDF-1.4
|
||||
%“Œ‹ž ReportLab Generated PDF document (opensource)
|
||||
1 0 obj
|
||||
<<
|
||||
/F1 2 0 R /F2 3 0 R /F3 4 0 R
|
||||
>>
|
||||
endobj
|
||||
2 0 obj
|
||||
<<
|
||||
/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
3 0 obj
|
||||
<<
|
||||
/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
4 0 obj
|
||||
<<
|
||||
/BaseFont /ZapfDingbats /Name /F3 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
5 0 obj
|
||||
<<
|
||||
/Contents 9 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 8 0 R /Resources <<
|
||||
/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
|
||||
>> /Rotate 0 /Trans <<
|
||||
|
||||
>>
|
||||
/Type /Page
|
||||
>>
|
||||
endobj
|
||||
6 0 obj
|
||||
<<
|
||||
/PageMode /UseNone /Pages 8 0 R /Type /Catalog
|
||||
>>
|
||||
endobj
|
||||
7 0 obj
|
||||
<<
|
||||
/Author (\(anonymous\)) /CreationDate (D:20260606193924+00'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260606193924+00'00') /Producer (ReportLab PDF Library - \(opensource\))
|
||||
/Subject (\(unspecified\)) /Title (\(anonymous\)) /Trapped /False
|
||||
>>
|
||||
endobj
|
||||
8 0 obj
|
||||
<<
|
||||
/Count 1 /Kids [ 5 0 R ] /Type /Pages
|
||||
>>
|
||||
endobj
|
||||
9 0 obj
|
||||
<<
|
||||
/Filter [ /ASCII85Decode /FlateDecode ] /Length 1950
|
||||
>>
|
||||
stream
|
||||
Gb"/'9lo&I&A@sBm*X'K%)56%3jp"UC6Dc*jlt.pOcY6`,T$NgUAXj?5Z4<rI7:9951CXC"+n<@*ZfL^_>tU**V2M@!%u=]p=]PfL%,ishst4R$/UZf^7Ee;Om_F;@K#$iCo8@9nGF_IH@Sr?*e[SHGP_kp^1BAl07\$Hk8,qC/%???UC/[qiFXcs0&0dG#>)3FV3(2Vbj_+Z@/LbZDm[4OUlK)uT&&.kF@9^TSCWKLk^,*2FDF*e6"$CYI9\ROgST>HAK-"[hqMo_>[+Db2,LeG.uaBS_Z"P,ec\dk=B-m!T&3P>G@<`N8bica4D"&gnY`uZhRL&N6.\-\T[u0e"D5+emGRf='Esg;8=k>U@R_)ofd;M:CkbgUTM6f@grc^N/21UR4C`RtB<p4#dFC*^/"r-NEgje.$YVn=_,*GAF%'1`Tr<8[Xs':"/0T:44!84\1Lra;']XJFK(B:%nWdK]RT7f)`i:k-oHkt9Q*b]e3-$V&p3SEFG+/Y9hpXgZr.u!G33F'Ln(C_U,.kH^++8e+RgkV+_(f3Ba/;*Z/%,M>gB4Nm"V%Vs<UH\oE4so9Gu!:$^?pTOc<b#\Yb**?q!L`&Ns*X^=G#Np?1$,"`LLTN)(!H?8cN1aV0E4lV2X#Cq&ih[;Bkfo&V02<AGrq[.hY%dQmN1Re&,radFuU[!>7Vj;hBqb[tc=K)K94JT7!K?@S]Lqk;4\2BNfqT;^`q,JB+,dWV#.eJjVjZ=JQQF9[.j^JE9S:E0eg8.NUfh":DuR!r`H(I6Fn\\*"!`Tq4Dchk+%h!/p!$BBs&fXVC1sLY[DtDnNO1hmL2N5#'C>G@7K9n=k(2[[I\b1p%7(<?7+WX5MQp<fPh]QX(1ekcZ6/p(*nsJIdA3WHkK"aN^(^`C>=3SX]c%4_WL8mnQW",6:)"Q>987P"FSW\qJ%mk(\fT#q8@kR*_;OKIepQ$j-d,[<2hO3A5%:<J$r@/>8HI0[EHD>'AIR>nA/MY*OSD&=k.(-7';8;qX"q8`Y,bi#&1:^*_"pYoGQ)<oJenEkXU%kA+/H*CWO$Hj[-O`#K?j:F%OVmZb55g$a8<R!38\D;]Vdr+D\sSddYTNRaY6qH9E_r%27AAD+-!^.7_B6q<PV`8tJ8;o(9"/.lPFjT,%7ITI;&,;2JZ+!,.0m400;_$^-h"^&1F3!lXq6u$=5(_FmlcoS2B!6fMIZ6'h=<enNpkdU[*8=K+'"K%31X/3B,6b&.Qr]B)Miqh$0!XB?/iUKr*l!Vr&A4e`:b.Mj:(!ZGcd5<skp_qLnH1B)A>]WVuX?^?We:DNaJqMR8*E7JVMK'8n+:7H+knGY%17eT19lt3'@N?id_1#?@N1!PJ#tp[i*Wr5(mS@7ts)9=<T#0dPY"8g7W-&Pi\BaU1kk3OFG9?9\XNJ&I1)?s)(NKI]NH'5bo<EWsloMTH@[4nD\(Y@,*=<O:M]ioXJ_Vj`L<9hMSFp,+S$SG0/hR?\metsQGL6;-J,*PBKs:XLEaiQ;I(9#8m(b]AqBFPC#[/\I"kC"MMR@ue/_a#P2Fa;krp5Y_hgHR&J*u1LO%)(;j-M5U7Y56RbV0YE"W+\],jFS^VcSmUM$o8$3kuOK_Yu2=p6?AaD=8"GDA`>IS#)`d/s$Bh_YbO`hGq,ue63$P$eG&56u/gFAWFu7/@GOk=IP:J]M-Mu#TS7aUpVoa)bk:"EO8Wm1!+Fu[3[XR$Q??#MZG&5<S3f*PBBP\-GR0DIfL_f#T^B3/[[5QC9L4/'gJa7XApT2_G0nbkl8(-^FVbORPU0DHF!`+nGMQ*D3X?9BZ#Mpa57D[iC'k8i4$DpAM=>0jNXa"lJ_q>6DM2D9as#*q3ht&=&sai+;DNo:#G[("M.u`4_7TZgJuce0l`r![;H_BS+Y_pi:sKAd^QnL%@jkA?QiBAHA%.:lPobeqEG0*Y:\8_lu-X,H(Y~>endstream
|
||||
endobj
|
||||
xref
|
||||
0 10
|
||||
0000000000 65535 f
|
||||
0000000061 00000 n
|
||||
0000000112 00000 n
|
||||
0000000219 00000 n
|
||||
0000000331 00000 n
|
||||
0000000414 00000 n
|
||||
0000000617 00000 n
|
||||
0000000685 00000 n
|
||||
0000000965 00000 n
|
||||
0000001024 00000 n
|
||||
trailer
|
||||
<<
|
||||
/ID
|
||||
[<3582204efdf198252eedc770c1bbf136><3582204efdf198252eedc770c1bbf136>]
|
||||
% ReportLab generated PDF document -- digest (opensource)
|
||||
|
||||
/Info 7 0 R
|
||||
/Root 6 0 R
|
||||
/Size 10
|
||||
>>
|
||||
startxref
|
||||
3065
|
||||
%%EOF
|
||||
86
agent_framework_oci/docs/04_support_agent_sla_policy.pdf
Normal file
86
agent_framework_oci/docs/04_support_agent_sla_policy.pdf
Normal file
@@ -0,0 +1,86 @@
|
||||
%PDF-1.4
|
||||
%“Œ‹ž ReportLab Generated PDF document (opensource)
|
||||
1 0 obj
|
||||
<<
|
||||
/F1 2 0 R /F2 3 0 R /F3 4 0 R /F4 5 0 R
|
||||
>>
|
||||
endobj
|
||||
2 0 obj
|
||||
<<
|
||||
/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
3 0 obj
|
||||
<<
|
||||
/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
4 0 obj
|
||||
<<
|
||||
/BaseFont /Courier /Encoding /WinAnsiEncoding /Name /F3 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
5 0 obj
|
||||
<<
|
||||
/BaseFont /ZapfDingbats /Name /F4 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
6 0 obj
|
||||
<<
|
||||
/Contents 10 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 9 0 R /Resources <<
|
||||
/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
|
||||
>> /Rotate 0 /Trans <<
|
||||
|
||||
>>
|
||||
/Type /Page
|
||||
>>
|
||||
endobj
|
||||
7 0 obj
|
||||
<<
|
||||
/PageMode /UseNone /Pages 9 0 R /Type /Catalog
|
||||
>>
|
||||
endobj
|
||||
8 0 obj
|
||||
<<
|
||||
/Author (\(anonymous\)) /CreationDate (D:20260606193924+00'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260606193924+00'00') /Producer (ReportLab PDF Library - \(opensource\))
|
||||
/Subject (\(unspecified\)) /Title (\(anonymous\)) /Trapped /False
|
||||
>>
|
||||
endobj
|
||||
9 0 obj
|
||||
<<
|
||||
/Count 1 /Kids [ 6 0 R ] /Type /Pages
|
||||
>>
|
||||
endobj
|
||||
10 0 obj
|
||||
<<
|
||||
/Filter [ /ASCII85Decode /FlateDecode ] /Length 1815
|
||||
>>
|
||||
stream
|
||||
Gb!#\?ZV\r&:`$(fLK;hTch.d^"fEsVUM$[1i8Vja,CG4XTjk;M<=a'D^E2ReCYggR;4Q9(6WiBqsV!E%p]&,luuJ3]Lh)TXTonuF9Q"/"H\(cGNmYeX*,gJ'8a&/h`IOt,mt6T5NUU8n65,9_HA-0n\>YTf*e>bdLp.NCK>/ZQ*b't69`8a[iaNH^>-@+7E]Pa+;\0digSaIr<hd>_llkco,Zi&d?*Q4>r1tr4$KG+h3J4YjbUe#5rfT@1JYQ*H76',JYDi7Q2kpLR>FoI&r;0"-9.X[0Y=Nt>9S-1&gR4#,Pa4PJ%PecjmZ#V[%NkGWfu[n8Ag=0>Y*kF("2Q(oKm>ufEaLLX6!A1Ad-O\Y*fL**\)2`k9>r3o(3\-C"Raq$.^7^hse=&*B+=g."V!sB'G&NcB<C$h?&^XVYI`33NRme^@!!9TOB@iGE,=Hm<*#:?rST@![mVpC<1&l9*UPnak:k`[bQ#gE\1e.K/7i%QoN"n+p&.]mfH8DRm2/s`3WOT03UX!]2$"(f=pqkA.GYA"81<FZ&W:&Vi@+XWrh]NTi'g&SO-ha0r/FkH#qDK?:^U%obLK*X2Y2OVgTeCJ4q/:-[A;F%^ZcNY^``%W:Pe4aGheuQOfNtO%dkC':#R*o_n`X`i8#$eZ?p(8Lrf=Obl:oLbC:m-.:)d/M#%\C.g@+rl>b`%I=<:;E7rY4S:.%:1BIU[N)[[(nHrS/'d3%G+?JXPCOF:.-AknmXaP7c!"gY1AUF\G"3DLKqGPM:/%B)6jS,4r:9j0+X&sjJQs6_)+OkcgBk@hhAs7P&*nNlNfsdErWJ7m#s[iRi2E-\Csnfg;)@/7;56UuBg68kI3)&=@<+or`tu\9R0@"S&Tg^8c7li\!qYumIiLG1o,'Rs2')7r?D;sZ9$RdDP]>"hW.I>uc(SZ.YKJqBpj-Eo,a2IP=*EM=q[7C8eVGfib)/5mR&r3Z<(qc()$<`ON37GMRTWBC7ES5RjQ^`Fl`qE8mEB_m*JTD]>DA##R%q<m;)#RbYtXb(D(mTG1BVJ15ZC"#b98>AIhJJbG>c65,6f(rS50D()5Kt-,;GTq;BO5^P<fs)ji&?#I1icc'sAIc9MTflEA8>C)]*uY>l@X,_$U*fcnr$'@MjA@C3bnjK;4VWR)Gam.PHL4!u%%Hr#>oMVW]05N\82arOV#+fHW20YqHNGXU(][(a,9;`4j$H:G;44GTo*gg-F;JJnO+PFC=7'DuW?`L6(SR%6?%:kVu#foi;Km2QXcMMF!5(B-7R`WZF?Hd!#oC1u#Y#9M859Z*<*k@1[;d.pc'U6\DHdQG:!9Op3]O5aI5:bVjVS(dVkC67i*C6q^pb)6=C%QOMWfIGUS:]#/e$g'1ZIP_Lk]L_X*'Ks*>A*:jqnO^2$Wg88m4:Q:IrBY:eZM$=FLM+BFRjs1<nM?A,&ZtSjE2<L@KF5f09YnK!&rT9AVgG<c,*c#Rq>1EP-7eSPkfUJ;S)[;=fD-6L6E2A&nLU#"mYg=!4MTbR`LUOX2%]bCgeS'B733/mY)Xjg$ENNZ&F(c^oX0r-5gnef:>8]EVm0D3><O$=Ec6Q%6(oXRh8p6?Z__X_3+]F<MI`'an.%oV[LZaXp^L:tmIU#^rP$[u%]14q0gNA$R<k.)@L04U-5>q@JC+BXO827-&Z)mK)\R=C=jomoL]Bl'th&"G?ec.V4(9c>1r-rJG9//^akdYJU)E-FKF@rU2Ogme&Oo$XWUaO,<5M7FJ<\mD"j_f,gB9RN-.dn"hK\io*R.,]Cf9;(hD+b"R].LP'[hM%.lQuDsqqXA>r<oC$^A.~>endstream
|
||||
endobj
|
||||
xref
|
||||
0 11
|
||||
0000000000 65535 f
|
||||
0000000061 00000 n
|
||||
0000000122 00000 n
|
||||
0000000229 00000 n
|
||||
0000000341 00000 n
|
||||
0000000446 00000 n
|
||||
0000000529 00000 n
|
||||
0000000733 00000 n
|
||||
0000000801 00000 n
|
||||
0000001081 00000 n
|
||||
0000001140 00000 n
|
||||
trailer
|
||||
<<
|
||||
/ID
|
||||
[<65cdb438fec3b059defed5f19a4ef77a><65cdb438fec3b059defed5f19a4ef77a>]
|
||||
% ReportLab generated PDF document -- digest (opensource)
|
||||
|
||||
/Info 8 0 R
|
||||
/Root 7 0 R
|
||||
/Size 11
|
||||
>>
|
||||
startxref
|
||||
3047
|
||||
%%EOF
|
||||
80
agent_framework_oci/docs/05_business_context_rag_flow.pdf
Normal file
80
agent_framework_oci/docs/05_business_context_rag_flow.pdf
Normal file
@@ -0,0 +1,80 @@
|
||||
%PDF-1.4
|
||||
%“Œ‹ž ReportLab Generated PDF document (opensource)
|
||||
1 0 obj
|
||||
<<
|
||||
/F1 2 0 R /F2 3 0 R /F3 4 0 R
|
||||
>>
|
||||
endobj
|
||||
2 0 obj
|
||||
<<
|
||||
/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
3 0 obj
|
||||
<<
|
||||
/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
4 0 obj
|
||||
<<
|
||||
/BaseFont /Courier /Encoding /WinAnsiEncoding /Name /F3 /Subtype /Type1 /Type /Font
|
||||
>>
|
||||
endobj
|
||||
5 0 obj
|
||||
<<
|
||||
/Contents 9 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 8 0 R /Resources <<
|
||||
/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ]
|
||||
>> /Rotate 0 /Trans <<
|
||||
|
||||
>>
|
||||
/Type /Page
|
||||
>>
|
||||
endobj
|
||||
6 0 obj
|
||||
<<
|
||||
/PageMode /UseNone /Pages 8 0 R /Type /Catalog
|
||||
>>
|
||||
endobj
|
||||
7 0 obj
|
||||
<<
|
||||
/Author (\(anonymous\)) /CreationDate (D:20260606193924+00'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260606193924+00'00') /Producer (ReportLab PDF Library - \(opensource\))
|
||||
/Subject (\(unspecified\)) /Title (\(anonymous\)) /Trapped /False
|
||||
>>
|
||||
endobj
|
||||
8 0 obj
|
||||
<<
|
||||
/Count 1 /Kids [ 5 0 R ] /Type /Pages
|
||||
>>
|
||||
endobj
|
||||
9 0 obj
|
||||
<<
|
||||
/Filter [ /ASCII85Decode /FlateDecode ] /Length 1679
|
||||
>>
|
||||
stream
|
||||
Gb"/'92jk1&AI`dqT)RQ=Rm^1@CM+q.(5Fq$)tJ4KVK(f[Uh!/-NANunfpoNX2<.j[K['XWS?^A]0E^R-=Gje1"RfS\/<'8J,l8sRK@I\(InG?p#tW4W0RQi&6aNGDg=5II0-JDr)l6LlIA&Tnj=<.E*UR5?JgB4!lsKM4=ss&Z\6*:quuLADkRERo,CLWa^P_n)3kNnquNR20KRVT\r.3AU5n&:?M&e3F!.#$^**.3&YIW6qOV=Cc4GCnZ#.G&ODSt0H=m<eeCHf^'+3?rqOni2-m)1ApnC_3j[rh$[,BgL@-PTh0SngP4;ojk.)"_4%C5ZZ.+sI%Bs82q,V%0nNZZD+PDY!_689.R%c^G<elq]ur_ABi[qK?;@/:<?Lh!NH[&GBP&BQcj;5%AD1oDHC-l9kXR^48'Kd=g\):Q\\GWnl)QAP7eaP&'%"BU;=C#d)#<9EB_#H"IV/i`^J$9ioJd0n!Mpikc'[>2qSYWKpq4MEBI>qQkaQ8'4I)J8gS3A5EhhcL;jAVF@iH]hq@1ZUphX[5Glc/A$\!=C8c[1?ZkD#phAT^IB<=XESPah&LR(YYK*%>SW:O=N$i,N@^BCD%peUck"585)J%%@AV"?;*YZKUS^7&7neQPcBfOZ:@TM?Kmpn&NBa5HrA4t`$oacN`[:],j9mf,YWak$T+%$R[Pqk9#bd3#NVXHVWloil,7+AU**pE9Ed$N;o.LN6CY#4h]n>VgJ*nId(\gSiEWo(Dm6[eqiMWiG!BqSoo>_@0qUT>gchup+:Q''"E:k10kNLm#f%TEp^%L9#QJVu5[]uehkU^AX2%'jY=2DtptU+(!k8N>d6V\l()>"Rh&rJU^kcYMg]krJ$KIs1/%'!=W,)tcq$cT7Vhf"`5gXUhC)&PZnC1#$VL3'5#Bs::n:pod.o>g>"a'"Vgs?G9b\_(G1)Np%n$C?rd,2R`?/IkcT8sO-e:k=[Q"hP<J6LHGq\1%-l1-]RoFJ%[%3KEmOcPN>"[8LYH6h!nS=V:*1rg!q7b*9QqJairdiks)3CYU(a_Y?b^(KD[iY5hlZI(2^;9QA(J#Jp#ArKDW\ek$RUH&i=%Yr^4YR.d"F.eY1cYijQd_il(<emg8%lCR?86[(,c@Kb\XB\tX37(Eu?uF0)6#5pf<YmdkP_lg3s2Mfl>@2;J^Ye=NOY"WZNad5i!kUO402:1/]oL,/AbpjWJ>5Tlot(8F2$,/h$?4K#YbZCE33!,"m8nkg&DBDZiQJ*%mrZ.&[AB5dp@$GafGX73M>7*JGrmD*?aT_h8*jTlppN?$IpRGBllsRlhb?>?p1Ck*PgK^1^ME;`g.O0u>L2!Ph9g1?EbNA(oPF\B@d+9P#/%n/D9\mrgMLZ=;<S2h45,IjJV&)CbY5pLdI?4R:F<Y+^qL(u?QjK,Y@TWD)N!nCUsYaS#hsHP*BS#[c%hb#9XUg9H0PS.3+pRtG$S\<=t7Z`<`h&k%\2M4,1hV^euAY7!ai,a8,'pk,@7On&&\:J[o_2!5LjO#$Ebtg(9[*YY-5!Gs1MQK,r0eGel=h@fZQc]D\*rJ;IR1=)-QR4N._L,]>"7SGuJu3hDh%_6H>'K1?AX'Vn].crdGji!iZ"o:5<2ar5[L'Qsh8?%&gKa8a>tjP'`R,Yg,qVHTfijAh67Mn0omJIJ?FHq[8F5!2Gg.U&~>endstream
|
||||
endobj
|
||||
xref
|
||||
0 10
|
||||
0000000000 65535 f
|
||||
0000000061 00000 n
|
||||
0000000112 00000 n
|
||||
0000000219 00000 n
|
||||
0000000331 00000 n
|
||||
0000000436 00000 n
|
||||
0000000639 00000 n
|
||||
0000000707 00000 n
|
||||
0000000987 00000 n
|
||||
0000001046 00000 n
|
||||
trailer
|
||||
<<
|
||||
/ID
|
||||
[<77932968a631fb1582c76a7d8a16a828><77932968a631fb1582c76a7d8a16a828>]
|
||||
% ReportLab generated PDF document -- digest (opensource)
|
||||
|
||||
/Info 7 0 R
|
||||
/Root 6 0 R
|
||||
/Size 10
|
||||
>>
|
||||
startxref
|
||||
2816
|
||||
%%EOF
|
||||
@@ -0,0 +1,17 @@
|
||||
# ADR — Motor de workflows transacionais no Agent Framework OCI
|
||||
|
||||
## Decisão
|
||||
|
||||
Adicionar ao framework uma capacidade opcional de execução determinística baseada em LangGraph. O motor é genérico; definições YAML e actions de domínio permanecem nos agentes.
|
||||
|
||||
## Razão
|
||||
|
||||
Operações multi-etapas com efeitos colaterais não devem depender do LLM para escolher a sequência crítica. A solução reduz tokens, latência e variação, além de melhorar auditoria, testes e versionamento.
|
||||
|
||||
## Compatibilidade
|
||||
|
||||
`execution.mode` assume `direct_tool`. Projetos existentes continuam usando MCP diretamente. A adoção de workflow é explícita por tool e pode ser controlada por `ENABLE_TRANSACTIONAL_WORKFLOWS`.
|
||||
|
||||
## Limites desta entrega
|
||||
|
||||
A base inclui validação, versionamento por arquivo, registry, execução sync/async, condições, retry por nó, cache de grafos e adapter de policy. Persistência corporativa de execution records, compensação/Saga, autorização por escopo e emissão de IC/NOC específica devem ser conectadas às abstrações existentes de cada deployment antes do uso em transações financeiras críticas.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Judges obrigatórios em interações transacionais
|
||||
|
||||
## Problema
|
||||
|
||||
Mesmo com `always_run_for_transactional: true`, os judges podiam ser ignorados
|
||||
pela amostragem porque o nó `judge` enviava apenas `context`, `route`, `intent` e
|
||||
`mcp_results`. Os campos transacionais produzidos pelo runtime não chegavam ao
|
||||
`JudgePipeline`.
|
||||
|
||||
## Correção
|
||||
|
||||
O nó `judge` agora repassa:
|
||||
|
||||
- `transaction_status`
|
||||
- `confirmation_required`
|
||||
- `confirmation_received`
|
||||
- `tool_policy_result`
|
||||
- `selected_tool_call`
|
||||
- `pending_tool_call`
|
||||
- `mcp_results` como evidência
|
||||
|
||||
O `JudgePipeline` detecta transações por múltiplos sinais e avalia
|
||||
`always_run_for_transactional` antes de aplicar `sample_rate`.
|
||||
|
||||
Com a configuração abaixo, consultas comuns continuam sendo amostradas em 25%,
|
||||
mas turnos `AWAITING_CONFIRMATION`, `COMPLETED`, `FAILED` ou `CANCELLED` executam
|
||||
os judges sempre.
|
||||
|
||||
```yaml
|
||||
enabled: true
|
||||
sample_rate: 0.25
|
||||
always_run_for_transactional: true
|
||||
```
|
||||
156
agent_framework_oci/docs/MCP_GATEWAY_DISCOVERY.md
Normal file
156
agent_framework_oci/docs/MCP_GATEWAY_DISCOVERY.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# MCP Gateway — Server Discovery and Catalog Sync
|
||||
|
||||
## Goal
|
||||
|
||||
This evolution allows the MCP Gateway to discover tools from registered MCP Servers by reading a manifest or catalog endpoint.
|
||||
|
||||
The framework still points to a single MCP Gateway:
|
||||
|
||||
```env
|
||||
MCP_GATEWAY_ENABLED=true
|
||||
MCP_GATEWAY_URL=http://localhost:8300
|
||||
MCP_GATEWAY_TIMEOUT_SECONDS=60
|
||||
```
|
||||
|
||||
The MCP Gateway can point to many MCP Servers:
|
||||
|
||||
```text
|
||||
Agent Framework
|
||||
-> MCP Gateway
|
||||
-> telecom_mcp_server
|
||||
-> retail_mcp_server
|
||||
-> nf_items_mcp_server
|
||||
-> any other MCP Server
|
||||
```
|
||||
|
||||
## What is automatic
|
||||
|
||||
After a server is registered in `apps/mcp_gateway/config/mcp_gateway.yaml` with `discover: true`, the gateway can:
|
||||
|
||||
- call its manifest/catalog endpoint;
|
||||
- normalize the returned tool list;
|
||||
- publish the tools in `GET /v1/tools`;
|
||||
- execute the discovered tool through `POST /v1/tools/{tool_name}/invoke`.
|
||||
|
||||
## What is still explicit
|
||||
|
||||
The gateway does not scan the network or GitHub by itself. You still register the MCP Server endpoint in YAML.
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
servers:
|
||||
nf_items:
|
||||
enabled: true
|
||||
discover: true
|
||||
protocol: legacy_http
|
||||
transport: http
|
||||
url: http://localhost:8400/mcp
|
||||
catalog_endpoint: /tools
|
||||
invoke_endpoint: /tools/call
|
||||
timeout_seconds: 30
|
||||
```
|
||||
|
||||
If `catalog_endpoint` is omitted, the gateway tries:
|
||||
|
||||
```text
|
||||
/.well-known/mcp-server.json
|
||||
/manifest
|
||||
/mcp/tools
|
||||
/tools/list
|
||||
/tools
|
||||
/v1/tools
|
||||
```
|
||||
|
||||
## Expected manifest/catalog formats
|
||||
|
||||
The gateway accepts common shapes:
|
||||
|
||||
```json
|
||||
{
|
||||
"server_id": "nf_items",
|
||||
"tools": [
|
||||
{
|
||||
"name": "buscar_notas_por_criterios",
|
||||
"description": "Search invoice items by criteria.",
|
||||
"input_schema": {
|
||||
"cliente": "string",
|
||||
"estado": "string",
|
||||
"preco": "number",
|
||||
"ean": "string",
|
||||
"margem": "number"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
It also accepts:
|
||||
|
||||
```json
|
||||
{"tools": [...]}
|
||||
```
|
||||
|
||||
```json
|
||||
{"data": {"tools": [...]}}
|
||||
```
|
||||
|
||||
```json
|
||||
{"capabilities": {"tools": [...]}}
|
||||
```
|
||||
|
||||
## New endpoints
|
||||
|
||||
### List discovery servers
|
||||
|
||||
```bash
|
||||
curl http://localhost:8300/v1/discovery/servers | jq
|
||||
```
|
||||
|
||||
### Force catalog sync
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8300/v1/discovery/sync | jq
|
||||
```
|
||||
|
||||
### List merged static + discovered tools
|
||||
|
||||
```bash
|
||||
curl http://localhost:8300/v1/tools | jq
|
||||
```
|
||||
|
||||
## Precedence rule
|
||||
|
||||
Static tools configured under `tools:` override discovered tools with the same name. This allows operations teams to override timeout, cache, allowed agents, required business keys, and endpoint behavior safely.
|
||||
|
||||
## Plugging a new MCP Server
|
||||
|
||||
1. Start the MCP Server.
|
||||
2. Confirm that it exposes a catalog or manifest endpoint.
|
||||
3. Add it under `servers:` in `mcp_gateway.yaml` with `discover: true`.
|
||||
4. Restart the MCP Gateway or call `POST /v1/discovery/sync`.
|
||||
5. Confirm the tool appears in `GET /v1/tools`.
|
||||
6. Invoke the tool through the gateway.
|
||||
|
||||
## Example invocation
|
||||
|
||||
```bash
|
||||
curl -s -X POST http://localhost:8300/v1/tools/buscar_notas_por_criterios/invoke \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"tenant_id": "default",
|
||||
"agent_id": "telecom_contas",
|
||||
"channel": "web",
|
||||
"tool_name": "buscar_notas_por_criterios",
|
||||
"arguments": {
|
||||
"cliente": "CLIENTE-001",
|
||||
"estado": "SP",
|
||||
"preco": 100.0,
|
||||
"ean": "7890000000000",
|
||||
"margem": 0.05
|
||||
},
|
||||
"business_context": {
|
||||
"session_key": "session-001"
|
||||
}
|
||||
}' | jq
|
||||
```
|
||||
28
agent_framework_oci/docs/MODULAR_REMAP.md
Normal file
28
agent_framework_oci/docs/MODULAR_REMAP.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# Modular Remap - Agent Framework OCI
|
||||
|
||||
Esta entrega reorganiza o projeto para uma arquitetura corporativa modular, preservando o core existente e separando responsabilidades deployáveis.
|
||||
|
||||
## Mapa de remanejamento
|
||||
|
||||
| Origem | Destino |
|
||||
|---|---|
|
||||
| `agent_framework/` | `libs/agent_framework/` |
|
||||
| `agent_gateway/` | `apps/agent_gateway/` |
|
||||
| `channel_gateway/` | `apps/channel_gateway/` |
|
||||
| `agent_frontend/` | `apps/agent_frontend/` |
|
||||
| `agent_template_backend/` | `templates/agent_template_backend/` |
|
||||
| `agent_template_backend_day_zero/` | `templates/agent_template_backend_day_zero/` |
|
||||
| `mcp_servers/` | `mcp/servers/` |
|
||||
| `agent_certification_tests/` | `evals/certification/` |
|
||||
| `agent_framework_oci_evaluator/evaluator/` | `evals/offline/evaluator/` |
|
||||
|
||||
## Novos componentes
|
||||
|
||||
- `apps/ai_gateway`: camada de abstração e governança de modelos.
|
||||
- `apps/mcp_gateway`: camada de roteamento e governança de MCP servers.
|
||||
- `specs/`: documentação objetiva no formato Spec-Driven Development.
|
||||
- `deploy/k8s/`: manifests iniciais para componentes deployáveis.
|
||||
|
||||
## Intenção arquitetural
|
||||
|
||||
O framework permanece como núcleo reutilizável. A reorganização explicita fronteiras de responsabilidade e prepara a solução para governança, escala e operação corporativa.
|
||||
@@ -0,0 +1,14 @@
|
||||
# Otimizações de execução MCP, RAG e Judges
|
||||
|
||||
- `mcp_tools` permanece allowlist; somente a consulta selecionada por `selection_keywords` é executada.
|
||||
- Extração `strategy: hybrid` tenta `pattern` regex antes do perfil LLM.
|
||||
- RAG é ignorado quando MCP bem-sucedido é suficiente, salvo perguntas de política/regra.
|
||||
- `mcp_results` é fornecido como evidência ao groundedness judge.
|
||||
- `judges.yaml` aceita `sample_rate` e `always_run_for_transactional`.
|
||||
- Consultas estruturadas simples podem retornar resposta determinística sem LLM do agente.
|
||||
|
||||
## Mudança de consulta para ação transacional
|
||||
|
||||
A route stickiness é preemptada quando uma keyword explícita configurada em `routing.yaml` identifica outra intent/agente. Assim, uma sessão em `retail_order_tracking` muda para `retail_support_exchange_return` ao receber pedidos como “devolver pedido”. Além disso, respostas diretas de tools read-only são bloqueadas quando a mensagem contém `selection_keywords` de qualquer tool transacional registrada.
|
||||
|
||||
As palavras de ação ficam em `config/tools.yaml`; o runtime não mantém aliases de domínio hardcoded.
|
||||
55
agent_framework_oci/docs/README_rag_samples.md
Normal file
55
agent_framework_oci/docs/README_rag_samples.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# RAG Sample PDFs for agent_template_backend
|
||||
|
||||
These PDF files are synthetic, searchable sample documents created to validate the RAG embedding and retrieval flow of `agent_template_backend`.
|
||||
|
||||
## Files
|
||||
|
||||
- `01_billing_agent_invoice_policy.pdf` - sample knowledge for `billing_agent`
|
||||
- `02_orders_agent_lifecycle_policy.pdf` - sample knowledge for `orders_agent`
|
||||
- `03_product_agent_catalog_policy.pdf` - sample knowledge for `product_agent`
|
||||
- `04_support_agent_sla_policy.pdf` - sample knowledge for `support_agent`
|
||||
- `05_business_context_rag_flow.pdf` - sample knowledge about BusinessContext, identity.yaml and MCP parameter mapping
|
||||
|
||||
## How to use
|
||||
|
||||
Copy the PDF files to the backend documentation directory:
|
||||
|
||||
```bash
|
||||
mkdir -p agent_template_backend/docs/rag_samples
|
||||
cp *.pdf agent_template_backend/docs/rag_samples/
|
||||
```
|
||||
|
||||
For a local smoke test, use:
|
||||
|
||||
```env
|
||||
VECTOR_STORE_PROVIDER=sqlite
|
||||
EMBEDDING_PROVIDER=mock
|
||||
SQLITE_DB_PATH=./data/agent_framework.db
|
||||
RAG_TOP_K=4
|
||||
```
|
||||
|
||||
Then run:
|
||||
|
||||
```bash
|
||||
python scripts/generate_rag_embeddings.py \
|
||||
--docs-dir ./agent_template_backend/docs/rag_samples \
|
||||
--namespace default
|
||||
```
|
||||
|
||||
For production-like semantic embeddings with OCI Generative AI, use:
|
||||
|
||||
```env
|
||||
VECTOR_STORE_PROVIDER=autonomous
|
||||
EMBEDDING_PROVIDER=oci
|
||||
OCI_COMPARTMENT_ID=ocid1.compartment.oc1..xxxx
|
||||
OCI_REGION=us-chicago-1
|
||||
OCI_EMBEDDING_MODEL=cohere.embed-multilingual-v3.0
|
||||
```
|
||||
|
||||
## Suggested retrieval test questions
|
||||
|
||||
- What is a prorated charge?
|
||||
- When can the OrdersAgent open an exchange request?
|
||||
- Which SKU represents the AI Agents book?
|
||||
- What is the target response for a critical support ticket?
|
||||
- How does BusinessContext map customer_key to MCP tool parameters?
|
||||
@@ -0,0 +1,38 @@
|
||||
VALIDAÇÃO - GLOBAL SUPERVISOR
|
||||
|
||||
Alterações implementadas:
|
||||
|
||||
1. Framework
|
||||
- agent_framework.global_supervisor.models
|
||||
- agent_framework.global_supervisor.config
|
||||
- agent_framework.global_supervisor.session_store
|
||||
- agent_framework.global_supervisor.router
|
||||
- agent_framework.global_supervisor.client
|
||||
|
||||
2. Novo serviço
|
||||
- agent_gateway/app/main.py
|
||||
- agent_gateway/app/settings.py
|
||||
- agent_gateway/config/backends.yaml
|
||||
- agent_gateway/README.md
|
||||
- agent_gateway/Dockerfile
|
||||
- agent_gateway/docs/ARQUITETURA_GLOBAL_SUPERVISOR.md
|
||||
|
||||
3. Docker Compose
|
||||
- serviço agent-gateway adicionado na porta 8010.
|
||||
|
||||
Validações executadas:
|
||||
|
||||
- python3 -m compileall -q agent_framework/src/agent_framework/global_supervisor agent_gateway/app
|
||||
Resultado: OK
|
||||
|
||||
- Smoke test do roteamento híbrido:
|
||||
Entrada 1: "Minha fatura veio alta" -> contas
|
||||
Entrada 2: "e esse valor?" na mesma session_id -> contas por active_backend
|
||||
Resultado: OK
|
||||
|
||||
- Smoke test de import do app FastAPI:
|
||||
from app.main import app, registry, router
|
||||
Resultado: OK
|
||||
|
||||
Observação:
|
||||
- O proxy SSE do gateway foi deixado como etapa futura. O endpoint /gateway/message/sse já roteia e encaminha como mensagem normal; para SSE fim-a-fim, pode-se implementar proxy de /gateway/events/{session_id} para o backend ativo.
|
||||
@@ -0,0 +1,5 @@
|
||||
VALIDATION REPORT - guardrails parallel fail-fast + observer IC
|
||||
Date: 2026-06-03
|
||||
|
||||
compileall: OK
|
||||
smoke-tests: OK
|
||||
10
agent_framework_oci/docs/features/README.md
Normal file
10
agent_framework_oci/docs/features/README.md
Normal file
@@ -0,0 +1,10 @@
|
||||
# Feature Guides / Guias de Features
|
||||
|
||||
Escolha o idioma / Choose a language:
|
||||
|
||||
- [Português (PT-BR)](pt-BR/README.md)
|
||||
- [English (EN)](en/README.md)
|
||||
|
||||
Os 15 arquivos bilíngues originais continuam neste diretório para compatibilidade, mas as árvores `pt-BR/` e `en/` são as versões recomendadas para leitura e distribuição.
|
||||
|
||||
The original 15 bilingual files remain in this directory for backward compatibility, but the `pt-BR/` and `en/` trees are the recommended versions for reading and distribution.
|
||||
83
agent_framework_oci/docs/features/en/01_authentication.md
Normal file
83
agent_framework_oci/docs/features/en/01_authentication.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# Authentication
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `security/authentication.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Checks who may access protected APIs, gateways, and services before the request reaches the agent.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
Client/System
|
||||
↓
|
||||
Authentication Provider
|
||||
↓
|
||||
valid credential?
|
||||
├─ no → 401/deny
|
||||
└─ yes → authenticated principal → agent
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The framework exposes an `AuthenticationProvider` abstraction with multiple implementations. Current providers include `NoAuthenticationProvider`, `DenyAuthenticationProvider`, `BasicAuthenticationProvider`, `ApiKeyAuthenticationProvider`, `StaticBearerAuthenticationProvider`, `JwtAuthenticationProvider`, `OAuth2IntrospectionAuthenticationProvider`, and `TrustedProxyAuthenticationProvider`.
|
||||
|
||||
Authentication produces an `AuthenticatedPrincipal` containing `subject`, `scheme`, and optional `claims`. Domain code should not validate credentials directly.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```python
|
||||
from agent_framework.security.authentication import BasicAuthenticationProvider
|
||||
|
||||
provider = BasicAuthenticationProvider(
|
||||
client_id="client-a",
|
||||
secret_hash="pbkdf2_sha256:...",
|
||||
)
|
||||
result = await provider.authenticate(request)
|
||||
if not result.authenticated:
|
||||
# deny access
|
||||
...
|
||||
```
|
||||
|
||||
Secrets may be verified as plain, SHA-256, or PBKDF2 values; for production, prefer strong hashes and managed secret stores.
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- Basic auth returns 401: validate the `Authorization: Basic ...` header and configured secret.
|
||||
- Do not confuse API authentication with `OCI_AUTH_MODE`; they solve different problems.
|
||||
- Avoid `NoAuthenticationProvider` in production unless explicitly accepted by architecture.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/security/authentication.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,92 @@
|
||||
# Deterministic Transactional Workflow
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `workflows/runtime.py + mcp/tool_policy.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Ensures state-changing operations follow predictable steps with confirmation and execution control instead of depending on LLM creativity.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
Customer message
|
||||
↓
|
||||
LLM understands intent
|
||||
↓
|
||||
Tool policy = transactional
|
||||
↓
|
||||
Deterministic workflow
|
||||
↓
|
||||
confirmation
|
||||
↓
|
||||
controlled execution
|
||||
↓
|
||||
result
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The LLM may help interpret intent and extract parameters, but it should not decide the critical sequence of a transaction. `ToolPolicyRegistry` classifies tools, and `operation_type: transactional` activates transactional behavior. `WorkflowRuntime` executes the workflow, preserves state, and integrates pause/resume and error recovery.
|
||||
|
||||
`ENABLE_TRANSACTIONAL_WORKFLOWS` controls the capability globally, while `WORKFLOWS_PATH` points to workflow YAML files.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
cancel_service:
|
||||
operation_type: transactional
|
||||
requires_confirmation: true
|
||||
```
|
||||
|
||||
```text
|
||||
1. locate service
|
||||
2. validate eligibility
|
||||
3. ask for confirmation
|
||||
4. PAUSE
|
||||
5. receive confirmation
|
||||
6. RESUME
|
||||
7. execute side effect
|
||||
```
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- Marking a write tool as `read_only` bypasses transactional protections.
|
||||
- Re-running steps before a pause can duplicate side effects; use the official runtime.
|
||||
- Do not use prompts as the only confirmation guarantee.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/workflows/runtime.py`
|
||||
- `libs/agent_framework/src/agent_framework/mcp/tool_policy.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,79 @@
|
||||
# Domain Requested LLM Composition
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `runtime/agent_runtime.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Lets domain logic compute the authoritative result and ask the LLM only to compose the final user-facing response.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
Domain logic computes
|
||||
↓
|
||||
requires_llm_composition=true
|
||||
↓
|
||||
framework prevents direct MCP answer
|
||||
↓
|
||||
official LLMProvider
|
||||
↓
|
||||
natural-language response
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The domain returns authoritative data plus a composition instruction. `AgentRuntimeMixin` recursively detects `requires_llm_composition` in tool/workflow results and avoids terminating through the direct MCP-answer path. Composition then uses the agent's official LLM provider, preserving profiles, tracing, usage accounting, and framework policies.
|
||||
|
||||
The LLM should compose language, not recalculate values or override already-resolved business rules.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"refund_amount": "38.00",
|
||||
"requires_llm_composition": true,
|
||||
"response_instruction": "Explain the refund using only the computed values."
|
||||
}
|
||||
```
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- An overly broad instruction may let the LLM add unauthorized content.
|
||||
- Do not delegate deterministic calculations back to the LLM.
|
||||
- If free-form wording is unnecessary, prefer a deterministic direct response.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,84 @@
|
||||
# Domain Requested RAG
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `runtime/agent_runtime.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Allows a tool or workflow to declare that external knowledge retrieval is required even when an MCP result already exists.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
Tool/Workflow
|
||||
↓
|
||||
requires_rag=true
|
||||
↓
|
||||
rag_query / rag_queries
|
||||
↓
|
||||
framework RagService
|
||||
↓
|
||||
Retrieval Guardrails
|
||||
↓
|
||||
LLM/response
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
Normally the framework may skip RAG when MCP already provides sufficient data (`SKIP_RAG_WHEN_MCP_SUFFICIENT`). This feature lets the domain override that decision for a specific case. A result may declare `requires_rag`, `rag_query`, or `rag_queries`; the runtime uses those queries as overrides and invokes `RagService`.
|
||||
|
||||
The domain declares **what knowledge is needed**. It does not implement its own vector client, retriever, or parallel RAG prompt stack.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```json
|
||||
{
|
||||
"requires_rag": true,
|
||||
"rag_queries": [
|
||||
"How to cancel YouTube Premium?",
|
||||
"How to cancel Aya Books?"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Related settings include `RAG_TOP_K` and `SKIP_RAG_WHEN_MCP_SUFFICIENT`.
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- Requesting RAG for transactional facts already resolved by an API adds unnecessary cost and latency.
|
||||
- Queries that are too broad reduce relevance.
|
||||
- Do not trust retrieved content for critical responses without Retrieval Guardrails.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
84
agent_framework_oci/docs/features/en/05_long_term_memory.md
Normal file
84
agent_framework_oci/docs/features/en/05_long_term_memory.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# Long Term Memory
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `memory/long_term_memory.py + memory/long_term_store.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Allows useful information to persist across different sessions without depending on the full transcript of a previous conversation.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
Session A
|
||||
↓
|
||||
extract relevant memory
|
||||
↓
|
||||
Long Term Memory Store
|
||||
↓
|
||||
... days later ...
|
||||
↓
|
||||
Session B
|
||||
↓
|
||||
retrieve relevant context
|
||||
↓
|
||||
agent
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
Long-term memory is different from message history and checkpoints. It persists useful facts/preferences and retrieves them as context for a future session. The framework supports `memory`, `sqlite`, `autonomous`, and `oracle` providers.
|
||||
|
||||
Important settings include `ENABLE_LONG_TERM_MEMORY`, `LONG_TERM_MEMORY_PROVIDER`, `LONG_TERM_MEMORY_MAX_CONTEXT_ITEMS`, `LONG_TERM_MEMORY_MIN_CONFIDENCE`, `LONG_TERM_MEMORY_AUTO_EXTRACT`, and `LONG_TERM_MEMORY_INJECT_CONTEXT`.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```env
|
||||
ENABLE_LONG_TERM_MEMORY=true
|
||||
LONG_TERM_MEMORY_PROVIDER=oracle
|
||||
LONG_TERM_MEMORY_MAX_CONTEXT_ITEMS=20
|
||||
LONG_TERM_MEMORY_MIN_CONFIDENCE=0.70
|
||||
LONG_TERM_MEMORY_AUTO_EXTRACT=true
|
||||
LONG_TERM_MEMORY_INJECT_CONTEXT=true
|
||||
```
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- Do not confuse LTM with replaying the entire transcript.
|
||||
- Irrelevant or low-confidence memories should not be injected.
|
||||
- For multiple replicas, prefer shared durable storage over local memory.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/memory/long_term_memory.py`
|
||||
- `libs/agent_framework/src/agent_framework/memory/long_term_store.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,82 @@
|
||||
# Offline Workflow Regression
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `workflows/runtime.py + Tuning-Performance/Offline_Workflow_Regression`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Allows workflow logic to be regression-tested without requiring the full production infrastructure.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
Test
|
||||
↓
|
||||
explicit deterministic test backend
|
||||
↓
|
||||
run → PAUSED
|
||||
↓
|
||||
resume → COMPLETED
|
||||
↓
|
||||
state/side-effect assertions
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
`WorkflowRuntime` includes an **explicitly opt-in deterministic/offline test backend**. When `allow_deterministic_fallback=True`, this backend is explicitly selected even if LangGraph is installed, keeping regression results reproducible across developer machines and CI. It can validate DSL rules, conditions, pause/resume behavior, and duplicate-execution protection without depending on LangGraph internals, a database, OCI, or external APIs.
|
||||
|
||||
Production behavior still uses LangGraph. Offline mode must never become a silent fallback when LangGraph fails or is unavailable in production.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```text
|
||||
run(workflow)
|
||||
action_a = executed once
|
||||
status = PAUSED
|
||||
|
||||
resume(workflow)
|
||||
action_a remains executed once
|
||||
action_b = executed once
|
||||
status = COMPLETED
|
||||
```
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- Using the offline backend in production hides real issues.
|
||||
- Over-mocking can stop the test from validating real DSL behavior.
|
||||
- Failing to assert pre-pause side effects may hide duplicate execution.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/workflows/runtime.py`
|
||||
- `libs/agent_framework/src/agent_framework/Tuning-Performance/Offline_Workflow_Regression`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,83 @@
|
||||
# Resume de Workflow / Pause / Resume Workflow
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `workflows/runtime.py + workflows/graph.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Allows a workflow to stop at a safe point, persist state, and continue later using user input or another event.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
Workflow
|
||||
↓
|
||||
pre-pause actions
|
||||
↓
|
||||
PAUSE
|
||||
↓
|
||||
checkpoint/state
|
||||
↓
|
||||
new message
|
||||
↓
|
||||
RESUME
|
||||
↓
|
||||
remaining actions
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
`WorkflowRuntime` exposes `arun(...)` and `aresume(...)`. The pause node is separated from the preceding action so previous side effects are not executed again on resume. The same `execution_id/thread_id` identifies the paused and resumed execution.
|
||||
|
||||
The runtime supports declarative conditions such as `all`, `any`, `not`, `eq`, `neq`, and `exists`, so pause/continue decisions do not need to live in the prompt.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```text
|
||||
status = await runtime.arun(...)
|
||||
# status == PAUSED
|
||||
|
||||
status = await runtime.aresume(execution_id, input={"confirmed": true})
|
||||
# status == COMPLETED
|
||||
```
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- Losing the `execution_id` prevents resuming the right execution.
|
||||
- Restarting the workflow from scratch after confirmation may duplicate side effects.
|
||||
- Pause without shared checkpoint/state storage is fragile across multiple replicas.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/workflows/runtime.py`
|
||||
- `libs/agent_framework/src/agent_framework/workflows/graph.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
76
agent_framework_oci/docs/features/en/08_route_stickiness.md
Normal file
76
agent_framework_oci/docs/features/en/08_route_stickiness.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# Route Stickiness
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `routing/enterprise_router.py + runtime/agent_runtime.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Prevents short follow-up messages from unnecessarily switching the conversation to another agent.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
current message
|
||||
+ short history
|
||||
+ previous route
|
||||
↓
|
||||
semantic continuity
|
||||
↓
|
||||
keep route or handoff
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
Route Stickiness evaluates whether a new message is semantically continuous with the current subject/agent. It reduces agent ping-pong for messages such as “what about that amount?”, “yes”, “the second one”, or “and last month?”.
|
||||
|
||||
Existing settings include `ENABLE_ROUTE_STICKINESS`, `ROUTE_STICKINESS_LLM_PROFILE`, `ROUTE_STICKINESS_CONFIDENCE_THRESHOLD`, `ROUTE_STICKINESS_HISTORY_TURNS`, and `ROUTE_STICKINESS_MAX_TOKENS`. The decision may still allow handoff when there is enough evidence of a topic change.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```env
|
||||
ENABLE_ROUTE_STICKINESS=true
|
||||
ROUTE_STICKINESS_CONFIDENCE_THRESHOLD=0.90
|
||||
ROUTE_STICKINESS_HISTORY_TURNS=2
|
||||
ROUTE_STICKINESS_MAX_TOKENS=80
|
||||
```
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- A threshold that is too low may trap the user on the wrong agent.
|
||||
- A threshold that is too high may lose continuity on short follow-ups.
|
||||
- Stickiness should not block explicit handoff when the user clearly changes intent.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/routing/enterprise_router.py`
|
||||
- `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,77 @@
|
||||
# Voice Interruption Replay
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `channels/interruption.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Decides whether audio received while the agent is speaking represents a new intent, a backchannel/noise event, or something that should simply replay/continue the previous speech.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
audio during speech
|
||||
↓
|
||||
InterruptionPolicy
|
||||
├─ process → new message
|
||||
├─ classify → lightweight classifier
|
||||
└─ replay → previous speech
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The policy lives in the framework rather than domain code. It distinguishes terminal sessions, `idle_nudge`, non-interruptible speech, and potentially interruptible speech. When needed, it may use a lightweight classifier backed by `LLMProvider`; on classification failure, it can fail safely to replay.
|
||||
|
||||
The goal is to prevent “uh-huh”, noise, echo, or residual audio fragments from being interpreted as a full new intent.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```text
|
||||
Agent: "Your invoice contains..."
|
||||
User: "uh-huh"
|
||||
→ replay/continue
|
||||
|
||||
Agent: "Your invoice contains..."
|
||||
User: "wait, I want to ask something else"
|
||||
→ process new intent
|
||||
```
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- Sending every noise fragment to an LLM increases latency and cost.
|
||||
- Allowing interruption during non-interruptible transactional speech may corrupt UX/state.
|
||||
- Replay should use a real previous utterance, not a technical envelope.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/channels/interruption.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,84 @@
|
||||
# Workflow Error Recovery
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `workflows/runtime.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Preserves partial execution state when a later step fails, making it possible to know what already happened and avoid repeating side effects.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
step A ✅
|
||||
step B ✅
|
||||
step C ❌
|
||||
↓
|
||||
FAILED + partial snapshot
|
||||
↓
|
||||
recovery decides what may continue/retry
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The runtime preserves the partial LangGraph snapshot when a later step fails and produces generic `error_details`. When an external exception provides structured information, HTTP status, body, attempt count, code, and metadata may be preserved.
|
||||
|
||||
This feature does not mean “retry everything”. Safe recovery depends on knowing what already executed, idempotency guarantees, and the nature of the failure.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "FAILED",
|
||||
"error_details": {
|
||||
"status": 503,
|
||||
"attempts": 3,
|
||||
"code": "UPSTREAM_UNAVAILABLE"
|
||||
},
|
||||
"state": {
|
||||
"protocol_created": true,
|
||||
"operation_completed": true,
|
||||
"sms_sent": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- Blind retries may repeat transactions.
|
||||
- If external exceptions discard metadata, recovery becomes less precise.
|
||||
- Always combine with Durable Idempotency for critical side effects.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/workflows/runtime.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
85
agent_framework_oci/docs/features/en/11_clarification.md
Normal file
85
agent_framework_oci/docs/features/en/11_clarification.md
Normal file
@@ -0,0 +1,85 @@
|
||||
# Clarification
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `runtime/agent_runtime.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
When required information is missing or a tool finds multiple options, the framework asks the user instead of guessing.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
ambiguous request
|
||||
↓
|
||||
NEEDS_CLARIFICATION
|
||||
↓
|
||||
question + options
|
||||
↓
|
||||
user answers
|
||||
↓
|
||||
framework resolves
|
||||
↓
|
||||
resume same tool/workflow
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The runtime supports clarification for both missing parameters and ambiguous tool results. For tool-result clarification, a result with `status: NEEDS_CLARIFICATION` may include options; the runtime persists `pending_tool_clarification`, moves to `TOOL_RESULT_CLARIFICATION`, and can resolve responses by ordinal or name.
|
||||
|
||||
After selection, the framework reuses the same tool and injects resolved arguments, preventing the router from treating a short reply as a brand-new intent.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "NEEDS_CLARIFICATION",
|
||||
"question": "Which service?",
|
||||
"options": [
|
||||
{"id": "tim_music", "label": "TIM Music"},
|
||||
{"id": "hbo_max", "label": "HBO Max"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
User: `the second one` → `hbo_max`.
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- Do not discard `pending_tool_clarification` between turns.
|
||||
- A short answer should be resolved against pending options before normal routing.
|
||||
- Options without stable identifiers/labels reduce resolution quality.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,82 @@
|
||||
# Durable Idempotency
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `idempotency.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Prevents the same critical operation from executing twice, including when a retry lands on another replica/pod.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
request
|
||||
↓
|
||||
idempotency key
|
||||
↓
|
||||
durable store
|
||||
├─ exists → return previous result
|
||||
└─ missing → execute → persist result
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
`create_idempotency_store(settings, ...)` chooses a backend according to configuration/platform. The framework provides `IdempotencyStore` and `InMemoryIdempotencyStore`, but distributed production should prefer shared storage. Settings include `IDEMPOTENCY_PROVIDER`, `IDEMPOTENCY_REQUIRE_DURABLE`, and `IDEMPOTENCY_TTL_SECONDS`.
|
||||
|
||||
Idempotency is different from retry: retry repeats an attempt; idempotency guarantees that repetition does not create another side effect.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```text
|
||||
Pod A receives cancellation
|
||||
→ key=customer:service:operation
|
||||
→ executes
|
||||
→ stores result
|
||||
|
||||
Pod A crashes
|
||||
|
||||
Pod B receives retry
|
||||
→ same key
|
||||
→ finds stored result
|
||||
→ DOES NOT cancel again
|
||||
```
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- An in-memory store across multiple pods is not durable idempotency.
|
||||
- A key that is too broad may block legitimate operations; too narrow may allow duplicates.
|
||||
- TTL should match the real retry/replay window.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/idempotency.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,79 @@
|
||||
# Dynamic Transaction States
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `runtime/agent_runtime.py + mcp/tool_policy.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Allows confirmation states to be derived from the current agent/domain instead of hardcoding every business domain into the framework.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
transactional tool
|
||||
↓
|
||||
current agent/domain
|
||||
↓
|
||||
WAITING_<PREFIX>_CONFIRMATION
|
||||
↓
|
||||
confirm/reject
|
||||
↓
|
||||
next state
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
Instead of maintaining fixed states such as `WAITING_BILLING_CONFIRMATION`, `WAITING_PRODUCT_CONFIRMATION`, and so on for every known domain, the runtime derives a prefix from the current agent and builds the confirmation state dynamically. This keeps the framework generic.
|
||||
|
||||
`operation_type` accepts `read_only`, `transactional`, `conversational`, and `internal`; only `transactional` enters the transactional confirmation path.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```text
|
||||
VasAgent + cancel_vas
|
||||
→ WAITING_VAS_CONFIRMATION
|
||||
|
||||
AddressAgent + change_address
|
||||
→ WAITING_ADDRESS_CONFIRMATION
|
||||
```
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- Hardcoding states in domain code reduces reuse.
|
||||
- Classifying a tool as `conversational` should not trigger transactional confirmation.
|
||||
- Changing agent identifiers may change state prefixes; keep IDs stable.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py`
|
||||
- `libs/agent_framework/src/agent_framework/mcp/tool_policy.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,80 @@
|
||||
# Post Finalization Replay
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `channels/interruption.py + config/settings.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Prevents residual audio or late messages from reopening a session that has already been finalized.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
terminal session
|
||||
↓
|
||||
residual input
|
||||
↓
|
||||
policy detects finalization
|
||||
↓
|
||||
replay last utterance/fallback
|
||||
↓
|
||||
DO NOT reopen LangGraph
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The interruption policy checks terminal-session metadata before treating an input as a new intent. When terminal speech is available, it uses `last_assistant_text`/`terminal_replay_text`; otherwise it may use `POST_FINALIZE_REPLAY_MESSAGE`.
|
||||
|
||||
The purpose is to protect the logical end of a session, especially on voice channels where audio packets may arrive after the finalization event.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```text
|
||||
Agent: "The interaction is complete."
|
||||
→ session finalized
|
||||
|
||||
late fragment arrives: "uh..."
|
||||
→ replay "The interaction is complete."
|
||||
→ no new routing / tool / LLM call
|
||||
```
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- If terminal state is not persisted, another replica may reopen the journey.
|
||||
- Do not replay technical/JSON envelopes as user-facing speech.
|
||||
- This feature does not replace an intentional new-session policy.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/channels/interruption.py`
|
||||
- `libs/agent_framework/src/agent_framework/config/settings.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,86 @@
|
||||
# Retrieval / Tool Guardrails
|
||||
|
||||
> `agent_framework_oci` feature — English guide.
|
||||
|
||||
**Main implementation:** `guardrails/pipeline.py + guardrails/rails.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. What it is
|
||||
|
||||
Applies safety and validation not only to user input and final output, but also to RAG-retrieved knowledge and tool arguments/results.
|
||||
|
||||
### 2. Problem it solves
|
||||
|
||||
Production agents should not rely on prompts alone to “do the right thing”. This feature moves a specific responsibility into a controlled framework layer, reducing unpredictable behavior and duplicate domain-agent code.
|
||||
|
||||
### 3. Simplified flow
|
||||
|
||||
```text
|
||||
User
|
||||
↓
|
||||
Input Guardrails
|
||||
↓
|
||||
RAG → Retrieval Guardrails
|
||||
↓
|
||||
LLM/Tool call → Tool Guardrails
|
||||
↓
|
||||
API
|
||||
↓
|
||||
Output Guardrails
|
||||
```
|
||||
|
||||
### 4. How it works internally
|
||||
|
||||
The framework has distinct guardrail stages. For retrieval, rails such as `RAGSEC` and `RET_REL` can validate retrieved-content safety and relevance. For tools, `TOOL_VAL` validates usage/arguments before or around execution.
|
||||
|
||||
Global settings include `ENABLE_INPUT_GUARDRAILS`, `ENABLE_OUTPUT_GUARDRAILS`, `ENABLE_PARALLEL_GUARDRAILS`, `GUARDRAILS_FAIL_FAST`, and `GUARDRAILS_CONFIG_PATH`. The agent YAML is the source of truth for enabled rails.
|
||||
|
||||
### 5. How to enable/configure
|
||||
|
||||
Exact activation depends on the template/agent. Check framework settings, YAML configuration, and the service template. Not every feature requires a global flag: some are activated by the contract returned from a tool/workflow.
|
||||
|
||||
### 6. Example
|
||||
|
||||
```yaml
|
||||
retrieval:
|
||||
rails:
|
||||
- RAGSEC
|
||||
- RET_REL
|
||||
|
||||
tool:
|
||||
rails:
|
||||
- TOOL_VAL
|
||||
```
|
||||
|
||||
Example: the question concerns canceling a service, but RAG retrieves modem documentation. `RET_REL` can reject that context before it is used in the answer.
|
||||
|
||||
### 7. Telemetry and observability
|
||||
|
||||
When the feature participates in an agent execution, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id`, and other correlation keys in state/events. This makes the decision observable through Langfuse/Observer without embedding observability logic in the domain.
|
||||
|
||||
### 8. How to test
|
||||
|
||||
1. Add a unit test for the core behavior.
|
||||
2. Add a runtime integration test when state spans multiple turns.
|
||||
3. Test the happy path and at least one failure/rejection path.
|
||||
4. Confirm retries/replays do not duplicate side effects for transactional features.
|
||||
5. In production, also validate telemetry and ID correlation.
|
||||
|
||||
### 9. Common mistakes
|
||||
|
||||
- Having a rail implementation does not mean it is enabled: check `guardrails.yaml`.
|
||||
- Fail-fast behavior should be chosen intentionally for each stage.
|
||||
- Tool guardrails do not replace business validation inside the API/action itself.
|
||||
|
||||
### 10. Relationship with other features
|
||||
|
||||
Use this feature together with the framework's horizontal capabilities rather than creating a parallel implementation in domain-agent code. For transactional journeys, pay special attention to **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery**, and **Guardrails**.
|
||||
|
||||
### 11. Repository references
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/guardrails/pipeline.py`
|
||||
- `libs/agent_framework/src/agent_framework/guardrails/rails.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
19
agent_framework_oci/docs/features/en/README.md
Normal file
19
agent_framework_oci/docs/features/en/README.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# Feature Guides — English (EN)
|
||||
|
||||
Documentation for the main `agent_framework_oci` features.
|
||||
|
||||
- [Authentication](01_authentication.md)
|
||||
- [Deterministic Transactional Workflow](02_deterministic_transactional_workflow.md)
|
||||
- [Domain Requested LLM Composition](03_domain_requested_llm_composition.md)
|
||||
- [Domain Requested RAG](04_domain_requested_rag.md)
|
||||
- [Long Term Memory](05_long_term_memory.md)
|
||||
- [Offline Workflow Regression](06_offline_workflow_regression.md)
|
||||
- [Resume de Workflow / Pause / Resume Workflow](07_pause_resume_workflow.md)
|
||||
- [Route Stickiness](08_route_stickiness.md)
|
||||
- [Voice Interruption Replay](09_voice_interruption_replay.md)
|
||||
- [Workflow Error Recovery](10_workflow_error_recovery.md)
|
||||
- [Clarification](11_clarification.md)
|
||||
- [Durable Idempotency](12_durable_idempotency.md)
|
||||
- [Dynamic Transaction States](13_dynamic_transaction_states.md)
|
||||
- [Post Finalization Replay](14_post_finalization_replay.md)
|
||||
- [Retrieval / Tool Guardrails](15_retrieval_tool_guardrails.md)
|
||||
83
agent_framework_oci/docs/features/pt-BR/01_authentication.md
Normal file
83
agent_framework_oci/docs/features/pt-BR/01_authentication.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# Autenticação
|
||||
|
||||
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
|
||||
|
||||
**Implementação principal:** `security/authentication.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. O que é
|
||||
|
||||
Verifica quem pode acessar APIs, gateways e serviços protegidos antes que a requisição chegue ao agente.
|
||||
|
||||
### 2. Problema que resolve
|
||||
|
||||
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
|
||||
|
||||
### 3. Fluxo simplificado
|
||||
|
||||
```text
|
||||
Cliente/Sistema
|
||||
↓
|
||||
Authentication Provider
|
||||
↓
|
||||
credencial válida?
|
||||
├─ não → 401/nega acesso
|
||||
└─ sim → principal autenticado → agente
|
||||
```
|
||||
|
||||
### 4. Como funciona internamente
|
||||
|
||||
O framework contém uma abstração `AuthenticationProvider` e implementações para cenários diferentes. Entre as implementações atuais estão `NoAuthenticationProvider`, `DenyAuthenticationProvider`, `BasicAuthenticationProvider`, `ApiKeyAuthenticationProvider`, `StaticBearerAuthenticationProvider`, `JwtAuthenticationProvider`, `OAuth2IntrospectionAuthenticationProvider` e `TrustedProxyAuthenticationProvider`.
|
||||
|
||||
A autenticação produz um `AuthenticatedPrincipal` com `subject`, `scheme` e, quando aplicável, `claims`. A regra de negócio do agente não deve validar senha/token diretamente.
|
||||
|
||||
### 5. Como ativar/configurar
|
||||
|
||||
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
|
||||
|
||||
### 6. Exemplo
|
||||
|
||||
```python
|
||||
from agent_framework.security.authentication import BasicAuthenticationProvider
|
||||
|
||||
provider = BasicAuthenticationProvider(
|
||||
client_id="client-a",
|
||||
secret_hash="pbkdf2_sha256:...",
|
||||
)
|
||||
result = await provider.authenticate(request)
|
||||
if not result.authenticated:
|
||||
# negar acesso
|
||||
...
|
||||
```
|
||||
|
||||
Segredos podem ser verificados em formato simples, SHA-256 ou PBKDF2; em produção, prefira hashes fortes e secret stores.
|
||||
|
||||
### 7. Telemetria e observabilidade
|
||||
|
||||
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
|
||||
|
||||
### 8. Como testar
|
||||
|
||||
1. Crie um teste unitário do comportamento principal.
|
||||
2. Crie um teste de integração do runtime quando houver estado entre turns.
|
||||
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
|
||||
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
|
||||
5. Em produção, valide também telemetria e correlação de IDs.
|
||||
|
||||
### 9. Erros comuns
|
||||
|
||||
- Basic auth retornando 401: validar `Authorization: Basic ...` e o secret configurado.
|
||||
- Confundir autenticação do usuário com `OCI_AUTH_MODE`: são problemas diferentes.
|
||||
- Usar `NoAuthenticationProvider` em produção sem decisão explícita de arquitetura.
|
||||
|
||||
### 10. Relação com outras features
|
||||
|
||||
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
|
||||
|
||||
### 11. Referências no repositório
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/security/authentication.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,92 @@
|
||||
# Workflow Transacional Determinístico
|
||||
|
||||
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
|
||||
|
||||
**Implementação principal:** `workflows/runtime.py + mcp/tool_policy.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. O que é
|
||||
|
||||
Garante que operações que alteram estado sigam passos previsíveis, com confirmação e controle de execução, em vez de depender da criatividade do LLM.
|
||||
|
||||
### 2. Problema que resolve
|
||||
|
||||
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
|
||||
|
||||
### 3. Fluxo simplificado
|
||||
|
||||
```text
|
||||
Mensagem do cliente
|
||||
↓
|
||||
LLM entende intenção
|
||||
↓
|
||||
Tool policy = transactional
|
||||
↓
|
||||
Workflow determinístico
|
||||
↓
|
||||
confirmação
|
||||
↓
|
||||
execução controlada
|
||||
↓
|
||||
resultado
|
||||
```
|
||||
|
||||
### 4. Como funciona internamente
|
||||
|
||||
O LLM pode ajudar a interpretar a intenção e extrair parâmetros, mas não deve decidir a sequência crítica de uma transação. O `ToolPolicyRegistry` classifica tools, e `operation_type: transactional` ativa a política transacional. O `WorkflowRuntime` executa o workflow, mantém estado e integra pause/resume e recuperação de erro.
|
||||
|
||||
A configuração `ENABLE_TRANSACTIONAL_WORKFLOWS` controla a capability global, e `WORKFLOWS_PATH` aponta para os YAMLs.
|
||||
|
||||
### 5. Como ativar/configurar
|
||||
|
||||
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
|
||||
|
||||
### 6. Exemplo
|
||||
|
||||
```yaml
|
||||
tools:
|
||||
cancelar_servico:
|
||||
operation_type: transactional
|
||||
requires_confirmation: true
|
||||
```
|
||||
|
||||
```text
|
||||
1. localizar serviço
|
||||
2. validar elegibilidade
|
||||
3. pedir confirmação
|
||||
4. PAUSE
|
||||
5. receber confirmação
|
||||
6. RESUME
|
||||
7. executar side effect
|
||||
```
|
||||
|
||||
### 7. Telemetria e observabilidade
|
||||
|
||||
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
|
||||
|
||||
### 8. Como testar
|
||||
|
||||
1. Crie um teste unitário do comportamento principal.
|
||||
2. Crie um teste de integração do runtime quando houver estado entre turns.
|
||||
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
|
||||
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
|
||||
5. Em produção, valide também telemetria e correlação de IDs.
|
||||
|
||||
### 9. Erros comuns
|
||||
|
||||
- Marcar uma tool de escrita como `read_only` elimina proteções transacionais.
|
||||
- Reexecutar steps anteriores ao pause pode duplicar side effects; use o runtime oficial.
|
||||
- Não use prompt como única garantia de confirmação.
|
||||
|
||||
### 10. Relação com outras features
|
||||
|
||||
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
|
||||
|
||||
### 11. Referências no repositório
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/workflows/runtime.py`
|
||||
- `libs/agent_framework/src/agent_framework/mcp/tool_policy.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,79 @@
|
||||
# Composição por LLM Solicitada pelo Domínio
|
||||
|
||||
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
|
||||
|
||||
**Implementação principal:** `runtime/agent_runtime.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. O que é
|
||||
|
||||
Permite que a regra de negócio calcule o resultado e peça ao LLM apenas para redigir a resposta final.
|
||||
|
||||
### 2. Problema que resolve
|
||||
|
||||
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
|
||||
|
||||
### 3. Fluxo simplificado
|
||||
|
||||
```text
|
||||
Regra de negócio calcula
|
||||
↓
|
||||
requires_llm_composition=true
|
||||
↓
|
||||
framework impede resposta MCP direta
|
||||
↓
|
||||
LLMProvider oficial
|
||||
↓
|
||||
redação natural
|
||||
```
|
||||
|
||||
### 4. Como funciona internamente
|
||||
|
||||
O domínio retorna dados confiáveis e uma instrução de composição. O `AgentRuntimeMixin` detecta `requires_llm_composition` de forma recursiva no resultado da tool/workflow e não encerra a resposta pelo caminho direto de MCP. A composição segue pelo LLM oficial do agente, preservando profiles, tracing, usage e políticas do framework.
|
||||
|
||||
O LLM deve redigir; ele não deve recalcular valores nem decidir regras de negócio já resolvidas.
|
||||
|
||||
### 5. Como ativar/configurar
|
||||
|
||||
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
|
||||
|
||||
### 6. Exemplo
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"refund_amount": "38,00",
|
||||
"requires_llm_composition": true,
|
||||
"response_instruction": "Explique a devolução usando somente os valores calculados."
|
||||
}
|
||||
```
|
||||
|
||||
### 7. Telemetria e observabilidade
|
||||
|
||||
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
|
||||
|
||||
### 8. Como testar
|
||||
|
||||
1. Crie um teste unitário do comportamento principal.
|
||||
2. Crie um teste de integração do runtime quando houver estado entre turns.
|
||||
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
|
||||
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
|
||||
5. Em produção, valide também telemetria e correlação de IDs.
|
||||
|
||||
### 9. Erros comuns
|
||||
|
||||
- Instrução muito aberta pode fazer o LLM adicionar conteúdo não autorizado.
|
||||
- Não envie ao LLM a responsabilidade de recalcular valores determinísticos.
|
||||
- Se não houver necessidade de redação livre, prefira resposta determinística direta.
|
||||
|
||||
### 10. Relação com outras features
|
||||
|
||||
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
|
||||
|
||||
### 11. Referências no repositório
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,84 @@
|
||||
# RAG Solicitado pelo Domínio
|
||||
|
||||
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
|
||||
|
||||
**Implementação principal:** `runtime/agent_runtime.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. O que é
|
||||
|
||||
Permite que uma tool ou workflow declare que a resposta precisa consultar conhecimento externo, mesmo quando já existe resultado MCP.
|
||||
|
||||
### 2. Problema que resolve
|
||||
|
||||
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
|
||||
|
||||
### 3. Fluxo simplificado
|
||||
|
||||
```text
|
||||
Tool/Workflow
|
||||
↓
|
||||
requires_rag=true
|
||||
↓
|
||||
rag_query / rag_queries
|
||||
↓
|
||||
RagService do framework
|
||||
↓
|
||||
Retrieval Guardrails
|
||||
↓
|
||||
LLM/resposta
|
||||
```
|
||||
|
||||
### 4. Como funciona internamente
|
||||
|
||||
Normalmente o framework pode pular RAG quando MCP já trouxe informação suficiente (`SKIP_RAG_WHEN_MCP_SUFFICIENT`). Esta feature permite que o domínio substitua essa decisão para um caso específico. O resultado pode declarar `requires_rag`, `rag_query` ou `rag_queries`; o runtime usa essas queries como override e executa o `RagService`.
|
||||
|
||||
O domínio informa **o que precisa saber**. Ele não implementa cliente de vetor, retriever ou prompt RAG paralelo.
|
||||
|
||||
### 5. Como ativar/configurar
|
||||
|
||||
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
|
||||
|
||||
### 6. Exemplo
|
||||
|
||||
```json
|
||||
{
|
||||
"requires_rag": true,
|
||||
"rag_queries": [
|
||||
"Como cancelar YouTube Premium?",
|
||||
"Como cancelar Aya Books?"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Configurações relacionadas incluem `RAG_TOP_K` e `SKIP_RAG_WHEN_MCP_SUFFICIENT`.
|
||||
|
||||
### 7. Telemetria e observabilidade
|
||||
|
||||
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
|
||||
|
||||
### 8. Como testar
|
||||
|
||||
1. Crie um teste unitário do comportamento principal.
|
||||
2. Crie um teste de integração do runtime quando houver estado entre turns.
|
||||
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
|
||||
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
|
||||
5. Em produção, valide também telemetria e correlação de IDs.
|
||||
|
||||
### 9. Erros comuns
|
||||
|
||||
- Declarar RAG para fatos transacionais já resolvidos pela API pode aumentar custo e latência.
|
||||
- Query genérica demais reduz relevância.
|
||||
- Nunca confie no retrieval sem `Retrieval Guardrails` quando o dado influencia resposta crítica.
|
||||
|
||||
### 10. Relação com outras features
|
||||
|
||||
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
|
||||
|
||||
### 11. Referências no repositório
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,84 @@
|
||||
# Memória de Longo Prazo
|
||||
|
||||
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
|
||||
|
||||
**Implementação principal:** `memory/long_term_memory.py + memory/long_term_store.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. O que é
|
||||
|
||||
Permite lembrar informações úteis entre sessões diferentes, sem depender do histórico completo de uma conversa.
|
||||
|
||||
### 2. Problema que resolve
|
||||
|
||||
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
|
||||
|
||||
### 3. Fluxo simplificado
|
||||
|
||||
```text
|
||||
Sessão A
|
||||
↓
|
||||
extração de memória relevante
|
||||
↓
|
||||
Long Term Memory Store
|
||||
↓
|
||||
... dias depois ...
|
||||
↓
|
||||
Sessão B
|
||||
↓
|
||||
recupera contexto relevante
|
||||
↓
|
||||
agente
|
||||
```
|
||||
|
||||
### 4. Como funciona internamente
|
||||
|
||||
A memória de longo prazo é diferente de histórico de mensagens e de checkpoint. Ela persiste fatos/preferências úteis e os recupera como contexto de uma nova sessão. O framework oferece providers `memory`, `sqlite`, `autonomous` e `oracle`.
|
||||
|
||||
Configurações importantes: `ENABLE_LONG_TERM_MEMORY`, `LONG_TERM_MEMORY_PROVIDER`, `LONG_TERM_MEMORY_MAX_CONTEXT_ITEMS`, `LONG_TERM_MEMORY_MIN_CONFIDENCE`, `LONG_TERM_MEMORY_AUTO_EXTRACT` e `LONG_TERM_MEMORY_INJECT_CONTEXT`.
|
||||
|
||||
### 5. Como ativar/configurar
|
||||
|
||||
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
|
||||
|
||||
### 6. Exemplo
|
||||
|
||||
```env
|
||||
ENABLE_LONG_TERM_MEMORY=true
|
||||
LONG_TERM_MEMORY_PROVIDER=oracle
|
||||
LONG_TERM_MEMORY_MAX_CONTEXT_ITEMS=20
|
||||
LONG_TERM_MEMORY_MIN_CONFIDENCE=0.70
|
||||
LONG_TERM_MEMORY_AUTO_EXTRACT=true
|
||||
LONG_TERM_MEMORY_INJECT_CONTEXT=true
|
||||
```
|
||||
|
||||
### 7. Telemetria e observabilidade
|
||||
|
||||
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
|
||||
|
||||
### 8. Como testar
|
||||
|
||||
1. Crie um teste unitário do comportamento principal.
|
||||
2. Crie um teste de integração do runtime quando houver estado entre turns.
|
||||
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
|
||||
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
|
||||
5. Em produção, valide também telemetria e correlação de IDs.
|
||||
|
||||
### 9. Erros comuns
|
||||
|
||||
- Não confundir LTM com replay de toda conversa.
|
||||
- Memória irrelevante ou de baixa confiança não deveria ser injetada.
|
||||
- Em múltiplas réplicas, prefira storage durável compartilhado em vez de memória local.
|
||||
|
||||
### 10. Relação com outras features
|
||||
|
||||
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
|
||||
|
||||
### 11. Referências no repositório
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/memory/long_term_memory.py`
|
||||
- `libs/agent_framework/src/agent_framework/memory/long_term_store.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,82 @@
|
||||
# Regressão Offline de Workflow
|
||||
|
||||
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
|
||||
|
||||
**Implementação principal:** `workflows/runtime.py + Tuning-Performance/Offline_Workflow_Regression`
|
||||
|
||||
---
|
||||
|
||||
### 1. O que é
|
||||
|
||||
Permite testar a lógica de workflows sem exigir toda a infraestrutura de produção.
|
||||
|
||||
### 2. Problema que resolve
|
||||
|
||||
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
|
||||
|
||||
### 3. Fluxo simplificado
|
||||
|
||||
```text
|
||||
Teste
|
||||
↓
|
||||
backend determinístico explicitamente habilitado
|
||||
↓
|
||||
run → PAUSED
|
||||
↓
|
||||
resume → COMPLETED
|
||||
↓
|
||||
asserts de estado/side effects
|
||||
```
|
||||
|
||||
### 4. Como funciona internamente
|
||||
|
||||
O `WorkflowRuntime` possui um caminho determinístico/offline **explicitamente opt-in para testes**. Quando `allow_deterministic_fallback=True`, esse backend é selecionado de forma explícita mesmo que LangGraph esteja instalado, garantindo regressões reproduzíveis entre máquinas e CI. Ele permite validar DSL, condições, pause/resume e proteção contra reexecução sem depender do comportamento interno do LangGraph, banco, OCI ou APIs externas.
|
||||
|
||||
O comportamento de produção continua usando LangGraph. O modo offline não deve virar fallback silencioso quando LangGraph falha ou está ausente em produção.
|
||||
|
||||
### 5. Como ativar/configurar
|
||||
|
||||
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
|
||||
|
||||
### 6. Exemplo
|
||||
|
||||
```text
|
||||
run(workflow)
|
||||
action_a = 1 execução
|
||||
status = PAUSED
|
||||
|
||||
resume(workflow)
|
||||
action_a continua com 1 execução
|
||||
action_b = 1 execução
|
||||
status = COMPLETED
|
||||
```
|
||||
|
||||
### 7. Telemetria e observabilidade
|
||||
|
||||
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
|
||||
|
||||
### 8. Como testar
|
||||
|
||||
1. Crie um teste unitário do comportamento principal.
|
||||
2. Crie um teste de integração do runtime quando houver estado entre turns.
|
||||
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
|
||||
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
|
||||
5. Em produção, valide também telemetria e correlação de IDs.
|
||||
|
||||
### 9. Erros comuns
|
||||
|
||||
- Usar o backend offline em produção mascara problemas reais.
|
||||
- Mockar tanto que o teste deixa de validar a DSL real.
|
||||
- Não verificar side effects anteriores ao pause pode esconder duplicações.
|
||||
|
||||
### 10. Relação com outras features
|
||||
|
||||
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
|
||||
|
||||
### 11. Referências no repositório
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/workflows/runtime.py`
|
||||
- `libs/agent_framework/src/agent_framework/Tuning-Performance/Offline_Workflow_Regression`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,83 @@
|
||||
# Pause
|
||||
|
||||
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
|
||||
|
||||
**Implementação principal:** `workflows/runtime.py + workflows/graph.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. O que é
|
||||
|
||||
Permite interromper um workflow em um ponto seguro, persistir o estado e continuar depois com a resposta do usuário ou outro evento.
|
||||
|
||||
### 2. Problema que resolve
|
||||
|
||||
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
|
||||
|
||||
### 3. Fluxo simplificado
|
||||
|
||||
```text
|
||||
Workflow
|
||||
↓
|
||||
ações prévias
|
||||
↓
|
||||
PAUSE
|
||||
↓
|
||||
checkpoint/estado
|
||||
↓
|
||||
nova mensagem
|
||||
↓
|
||||
RESUME
|
||||
↓
|
||||
ações seguintes
|
||||
```
|
||||
|
||||
### 4. Como funciona internamente
|
||||
|
||||
`WorkflowRuntime` expõe `arun(...)` e `aresume(...)`. O nó de pause é separado da action anterior para evitar reexecutar side effects quando o workflow retoma. O mesmo `execution_id/thread_id` identifica a execução pausada e retomada.
|
||||
|
||||
O runtime suporta condições declarativas como `all`, `any`, `not`, `eq`, `neq` e `exists`, permitindo definir quando pausar ou continuar sem colocar lógica conversacional no prompt.
|
||||
|
||||
### 5. Como ativar/configurar
|
||||
|
||||
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
|
||||
|
||||
### 6. Exemplo
|
||||
|
||||
```text
|
||||
status = await runtime.arun(...)
|
||||
# status == PAUSED
|
||||
|
||||
status = await runtime.aresume(execution_id, input={"confirmed": true})
|
||||
# status == COMPLETED
|
||||
```
|
||||
|
||||
### 7. Telemetria e observabilidade
|
||||
|
||||
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
|
||||
|
||||
### 8. Como testar
|
||||
|
||||
1. Crie um teste unitário do comportamento principal.
|
||||
2. Crie um teste de integração do runtime quando houver estado entre turns.
|
||||
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
|
||||
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
|
||||
5. Em produção, valide também telemetria e correlação de IDs.
|
||||
|
||||
### 9. Erros comuns
|
||||
|
||||
- Perder o `execution_id` impede retomar a execução correta.
|
||||
- Reexecutar o workflow do zero após confirmação pode repetir side effects.
|
||||
- Pause sem storage/checkpoint compartilhado é frágil em múltiplas réplicas.
|
||||
|
||||
### 10. Relação com outras features
|
||||
|
||||
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
|
||||
|
||||
### 11. Referências no repositório
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/workflows/runtime.py`
|
||||
- `libs/agent_framework/src/agent_framework/workflows/graph.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,76 @@
|
||||
# Aderência de Rota
|
||||
|
||||
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
|
||||
|
||||
**Implementação principal:** `routing/enterprise_router.py + runtime/agent_runtime.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. O que é
|
||||
|
||||
Evita que pequenas mensagens de continuação façam a conversa trocar de agente sem necessidade.
|
||||
|
||||
### 2. Problema que resolve
|
||||
|
||||
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
|
||||
|
||||
### 3. Fluxo simplificado
|
||||
|
||||
```text
|
||||
mensagem atual
|
||||
+ histórico curto
|
||||
+ rota anterior
|
||||
↓
|
||||
continuidade semântica
|
||||
↓
|
||||
manter rota ou handoff
|
||||
```
|
||||
|
||||
### 4. Como funciona internamente
|
||||
|
||||
Route Stickiness avalia se a nova mensagem continua semanticamente ligada ao assunto/agente atual. Isso reduz ping-pong de agentes em mensagens como “e esse valor?”, “sim”, “o segundo” ou “e no mês passado?”.
|
||||
|
||||
Configurações existentes incluem `ENABLE_ROUTE_STICKINESS`, `ROUTE_STICKINESS_LLM_PROFILE`, `ROUTE_STICKINESS_CONFIDENCE_THRESHOLD`, `ROUTE_STICKINESS_HISTORY_TURNS` e `ROUTE_STICKINESS_MAX_TOKENS`. A decisão pode permitir handoff quando há evidência suficiente de mudança de assunto.
|
||||
|
||||
### 5. Como ativar/configurar
|
||||
|
||||
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
|
||||
|
||||
### 6. Exemplo
|
||||
|
||||
```env
|
||||
ENABLE_ROUTE_STICKINESS=true
|
||||
ROUTE_STICKINESS_CONFIDENCE_THRESHOLD=0.90
|
||||
ROUTE_STICKINESS_HISTORY_TURNS=2
|
||||
ROUTE_STICKINESS_MAX_TOKENS=80
|
||||
```
|
||||
|
||||
### 7. Telemetria e observabilidade
|
||||
|
||||
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
|
||||
|
||||
### 8. Como testar
|
||||
|
||||
1. Crie um teste unitário do comportamento principal.
|
||||
2. Crie um teste de integração do runtime quando houver estado entre turns.
|
||||
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
|
||||
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
|
||||
5. Em produção, valide também telemetria e correlação de IDs.
|
||||
|
||||
### 9. Erros comuns
|
||||
|
||||
- Threshold muito baixo pode prender o cliente no agente errado.
|
||||
- Threshold alto demais perde continuidade em mensagens curtas.
|
||||
- Stickiness não deve bloquear handoff explícito quando a intenção realmente mudou.
|
||||
|
||||
### 10. Relação com outras features
|
||||
|
||||
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
|
||||
|
||||
### 11. Referências no repositório
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/routing/enterprise_router.py`
|
||||
- `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,77 @@
|
||||
# Replay em Interrupções de Voz
|
||||
|
||||
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
|
||||
|
||||
**Implementação principal:** `channels/interruption.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. O que é
|
||||
|
||||
Decide se um áudio recebido durante a fala do agente representa uma nova intenção, um ruído/backchannel ou algo que deve apenas repetir/continuar a última fala.
|
||||
|
||||
### 2. Problema que resolve
|
||||
|
||||
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
|
||||
|
||||
### 3. Fluxo simplificado
|
||||
|
||||
```text
|
||||
áudio durante fala
|
||||
↓
|
||||
InterruptionPolicy
|
||||
├─ process → nova mensagem
|
||||
├─ classify → classificador leve
|
||||
└─ replay → última fala
|
||||
```
|
||||
|
||||
### 4. Como funciona internamente
|
||||
|
||||
A política fica no framework, não no domínio. Ela diferencia sessão terminal, `idle_nudge`, fala não interrompível e fala potencialmente interrompível. Quando necessário, pode usar um classificador leve baseado no `LLMProvider`; quando a classificação falha, a política é conservadora e pode optar por replay.
|
||||
|
||||
O objetivo é evitar que “aham”, ruído, eco ou fragmentos residuais sejam tratados como uma nova intenção completa.
|
||||
|
||||
### 5. Como ativar/configurar
|
||||
|
||||
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
|
||||
|
||||
### 6. Exemplo
|
||||
|
||||
```text
|
||||
Agente: "Sua fatura possui..."
|
||||
Cliente: "aham"
|
||||
→ replay/continua
|
||||
|
||||
Agente: "Sua fatura possui..."
|
||||
Cliente: "espera, quero falar de outra coisa"
|
||||
→ processa nova intenção
|
||||
```
|
||||
|
||||
### 7. Telemetria e observabilidade
|
||||
|
||||
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
|
||||
|
||||
### 8. Como testar
|
||||
|
||||
1. Crie um teste unitário do comportamento principal.
|
||||
2. Crie um teste de integração do runtime quando houver estado entre turns.
|
||||
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
|
||||
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
|
||||
5. Em produção, valide também telemetria e correlação de IDs.
|
||||
|
||||
### 9. Erros comuns
|
||||
|
||||
- Classificar todo ruído com LLM aumenta latência e custo.
|
||||
- Permitir interrupção em fala transacional não interrompível pode corromper UX/estado.
|
||||
- Replay deve usar uma fala real anterior, não um envelope técnico.
|
||||
|
||||
### 10. Relação com outras features
|
||||
|
||||
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
|
||||
|
||||
### 11. Referências no repositório
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/channels/interruption.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,84 @@
|
||||
# Recuperação de Erro em Workflow
|
||||
|
||||
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
|
||||
|
||||
**Implementação principal:** `workflows/runtime.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. O que é
|
||||
|
||||
Preserva o estado parcial de uma execução quando um passo posterior falha, permitindo entender o que já aconteceu e evitar repetir side effects.
|
||||
|
||||
### 2. Problema que resolve
|
||||
|
||||
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
|
||||
|
||||
### 3. Fluxo simplificado
|
||||
|
||||
```text
|
||||
passo A ✅
|
||||
passo B ✅
|
||||
passo C ❌
|
||||
↓
|
||||
FAILED + snapshot parcial
|
||||
↓
|
||||
recovery decide o que pode continuar/repetir
|
||||
```
|
||||
|
||||
### 4. Como funciona internamente
|
||||
|
||||
O runtime preserva o snapshot parcial do LangGraph quando uma etapa posterior falha e produz `error_details` genérico. Quando a exceção externa possui informações estruturadas, podem ser preservados status HTTP, body, número de tentativas, code e metadata.
|
||||
|
||||
A feature não significa “tentar tudo de novo”. Recuperação segura depende de conhecer o estado já executado, a idempotência e a natureza do erro.
|
||||
|
||||
### 5. Como ativar/configurar
|
||||
|
||||
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
|
||||
|
||||
### 6. Exemplo
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "FAILED",
|
||||
"error_details": {
|
||||
"status": 503,
|
||||
"attempts": 3,
|
||||
"code": "UPSTREAM_UNAVAILABLE"
|
||||
},
|
||||
"state": {
|
||||
"protocol_created": true,
|
||||
"operation_completed": true,
|
||||
"sms_sent": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 7. Telemetria e observabilidade
|
||||
|
||||
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
|
||||
|
||||
### 8. Como testar
|
||||
|
||||
1. Crie um teste unitário do comportamento principal.
|
||||
2. Crie um teste de integração do runtime quando houver estado entre turns.
|
||||
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
|
||||
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
|
||||
5. Em produção, valide também telemetria e correlação de IDs.
|
||||
|
||||
### 9. Erros comuns
|
||||
|
||||
- Retry indiscriminado pode repetir transações.
|
||||
- Se a exceção externa perde metadata, a recuperação fica menos precisa.
|
||||
- Combine sempre com Durable Idempotency em side effects críticos.
|
||||
|
||||
### 10. Relação com outras features
|
||||
|
||||
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
|
||||
|
||||
### 11. Referências no repositório
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/workflows/runtime.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
85
agent_framework_oci/docs/features/pt-BR/11_clarification.md
Normal file
85
agent_framework_oci/docs/features/pt-BR/11_clarification.md
Normal file
@@ -0,0 +1,85 @@
|
||||
# Clarificação
|
||||
|
||||
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
|
||||
|
||||
**Implementação principal:** `runtime/agent_runtime.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. O que é
|
||||
|
||||
Quando faltam dados ou uma tool encontra múltiplas opções, o framework pergunta ao usuário em vez de adivinhar.
|
||||
|
||||
### 2. Problema que resolve
|
||||
|
||||
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
|
||||
|
||||
### 3. Fluxo simplificado
|
||||
|
||||
```text
|
||||
pedido ambíguo
|
||||
↓
|
||||
NEEDS_CLARIFICATION
|
||||
↓
|
||||
pergunta + opções
|
||||
↓
|
||||
usuário responde
|
||||
↓
|
||||
framework resolve
|
||||
↓
|
||||
retoma mesma tool/workflow
|
||||
```
|
||||
|
||||
### 4. Como funciona internamente
|
||||
|
||||
O runtime suporta clarificação tanto de parâmetros faltantes quanto de resultados de tools. Para tool-result clarification, um resultado com `status: NEEDS_CLARIFICATION` pode trazer opções; o runtime persiste `pending_tool_clarification`, entra em `TOOL_RESULT_CLARIFICATION` e consegue resolver respostas por ordinal ou nome.
|
||||
|
||||
Depois da escolha, o framework reutiliza a mesma tool e injeta os argumentos resolvidos, evitando que o roteador trate a resposta curta como uma intenção nova.
|
||||
|
||||
### 5. Como ativar/configurar
|
||||
|
||||
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
|
||||
|
||||
### 6. Exemplo
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "NEEDS_CLARIFICATION",
|
||||
"question": "Qual serviço?",
|
||||
"options": [
|
||||
{"id": "tim_music", "label": "TIM Music"},
|
||||
{"id": "hbo_max", "label": "HBO Max"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Usuário: `o segundo` → `hbo_max`.
|
||||
|
||||
### 7. Telemetria e observabilidade
|
||||
|
||||
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
|
||||
|
||||
### 8. Como testar
|
||||
|
||||
1. Crie um teste unitário do comportamento principal.
|
||||
2. Crie um teste de integração do runtime quando houver estado entre turns.
|
||||
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
|
||||
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
|
||||
5. Em produção, valide também telemetria e correlação de IDs.
|
||||
|
||||
### 9. Erros comuns
|
||||
|
||||
- Não descarte `pending_tool_clarification` entre turns.
|
||||
- Uma resposta curta deve ser resolvida contra as opções antes do roteamento normal.
|
||||
- Opções sem identificador/label consistente pioram a resolução.
|
||||
|
||||
### 10. Relação com outras features
|
||||
|
||||
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
|
||||
|
||||
### 11. Referências no repositório
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,82 @@
|
||||
# Idempotência Durável
|
||||
|
||||
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
|
||||
|
||||
**Implementação principal:** `idempotency.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. O que é
|
||||
|
||||
Impede que a mesma operação crítica seja executada duas vezes, inclusive quando outra réplica/pod recebe a repetição.
|
||||
|
||||
### 2. Problema que resolve
|
||||
|
||||
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
|
||||
|
||||
### 3. Fluxo simplificado
|
||||
|
||||
```text
|
||||
requisição
|
||||
↓
|
||||
idempotency key
|
||||
↓
|
||||
store durável
|
||||
├─ existe → retorna resultado anterior
|
||||
└─ não existe → executa → persiste resultado
|
||||
```
|
||||
|
||||
### 4. Como funciona internamente
|
||||
|
||||
`create_idempotency_store(settings, ...)` escolhe o backend conforme configuração/plataforma. O framework possui `IdempotencyStore` e `InMemoryIdempotencyStore`, mas produção distribuída deve preferir storage compartilhado. As configurações incluem `IDEMPOTENCY_PROVIDER`, `IDEMPOTENCY_REQUIRE_DURABLE` e `IDEMPOTENCY_TTL_SECONDS`.
|
||||
|
||||
Idempotência é diferente de retry: retry repete a tentativa; idempotência garante que a repetição não produza um novo side effect.
|
||||
|
||||
### 5. Como ativar/configurar
|
||||
|
||||
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
|
||||
|
||||
### 6. Exemplo
|
||||
|
||||
```text
|
||||
Pod A recebe cancelamento
|
||||
→ key=cliente:servico:operacao
|
||||
→ executa
|
||||
→ grava resultado
|
||||
|
||||
Pod A cai
|
||||
|
||||
Pod B recebe retry
|
||||
→ mesma key
|
||||
→ encontra resultado
|
||||
→ NÃO cancela de novo
|
||||
```
|
||||
|
||||
### 7. Telemetria e observabilidade
|
||||
|
||||
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
|
||||
|
||||
### 8. Como testar
|
||||
|
||||
1. Crie um teste unitário do comportamento principal.
|
||||
2. Crie um teste de integração do runtime quando houver estado entre turns.
|
||||
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
|
||||
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
|
||||
5. Em produção, valide também telemetria e correlação de IDs.
|
||||
|
||||
### 9. Erros comuns
|
||||
|
||||
- Usar store em memória com múltiplos pods não é idempotência durável.
|
||||
- Chave ampla demais pode bloquear operações legítimas; estreita demais permite duplicidade.
|
||||
- TTL deve ser compatível com a janela real de retry/replay.
|
||||
|
||||
### 10. Relação com outras features
|
||||
|
||||
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
|
||||
|
||||
### 11. Referências no repositório
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/idempotency.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,79 @@
|
||||
# Estados Transacionais Dinâmicos
|
||||
|
||||
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
|
||||
|
||||
**Implementação principal:** `runtime/agent_runtime.py + mcp/tool_policy.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. O que é
|
||||
|
||||
Permite criar estados de confirmação baseados no agente/domínio atual sem hardcode de todos os domínios dentro do framework.
|
||||
|
||||
### 2. Problema que resolve
|
||||
|
||||
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
|
||||
|
||||
### 3. Fluxo simplificado
|
||||
|
||||
```text
|
||||
tool transactional
|
||||
↓
|
||||
agente/domínio atual
|
||||
↓
|
||||
WAITING_<PREFIX>_CONFIRMATION
|
||||
↓
|
||||
confirmação/rejeição
|
||||
↓
|
||||
estado seguinte
|
||||
```
|
||||
|
||||
### 4. Como funciona internamente
|
||||
|
||||
Em vez de manter estados fixos como `WAITING_BILLING_CONFIRMATION`, `WAITING_PRODUCT_CONFIRMATION` etc. para cada domínio conhecido, o runtime deriva o prefixo do agente atual e gera o estado dinamicamente. A função interna de estado transacional mantém o framework genérico.
|
||||
|
||||
A classificação `operation_type` aceita `read_only`, `transactional`, `conversational` e `internal`; somente `transactional` entra no caminho de confirmação transacional.
|
||||
|
||||
### 5. Como ativar/configurar
|
||||
|
||||
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
|
||||
|
||||
### 6. Exemplo
|
||||
|
||||
```text
|
||||
VasAgent + cancelar_vas
|
||||
→ WAITING_VAS_CONFIRMATION
|
||||
|
||||
AddressAgent + alterar_endereco
|
||||
→ WAITING_ADDRESS_CONFIRMATION
|
||||
```
|
||||
|
||||
### 7. Telemetria e observabilidade
|
||||
|
||||
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
|
||||
|
||||
### 8. Como testar
|
||||
|
||||
1. Crie um teste unitário do comportamento principal.
|
||||
2. Crie um teste de integração do runtime quando houver estado entre turns.
|
||||
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
|
||||
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
|
||||
5. Em produção, valide também telemetria e correlação de IDs.
|
||||
|
||||
### 9. Erros comuns
|
||||
|
||||
- Hardcode de estados no domínio reduz reutilização.
|
||||
- Classificar uma tool como `conversational` não deve ativar confirmação transacional.
|
||||
- Mudanças no identificador do agente podem mudar o prefixo; mantenha IDs estáveis.
|
||||
|
||||
### 10. Relação com outras features
|
||||
|
||||
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
|
||||
|
||||
### 11. Referências no repositório
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/runtime/agent_runtime.py`
|
||||
- `libs/agent_framework/src/agent_framework/mcp/tool_policy.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,80 @@
|
||||
# Replay Após Finalização
|
||||
|
||||
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
|
||||
|
||||
**Implementação principal:** `channels/interruption.py + config/settings.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. O que é
|
||||
|
||||
Evita que áudio residual ou mensagens tardias reabram uma sessão já finalizada.
|
||||
|
||||
### 2. Problema que resolve
|
||||
|
||||
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
|
||||
|
||||
### 3. Fluxo simplificado
|
||||
|
||||
```text
|
||||
sessão terminal
|
||||
↓
|
||||
entrada residual
|
||||
↓
|
||||
policy detecta finalização
|
||||
↓
|
||||
replay última fala/fallback
|
||||
↓
|
||||
NÃO reabre LangGraph
|
||||
```
|
||||
|
||||
### 4. Como funciona internamente
|
||||
|
||||
A política de interrupção verifica metadata de sessão terminal antes de tratar uma entrada como nova intenção. Quando há texto terminal disponível, usa `last_assistant_text`/`terminal_replay_text`; caso contrário, pode usar a mensagem configurada em `POST_FINALIZE_REPLAY_MESSAGE`.
|
||||
|
||||
O objetivo é proteger o fechamento lógico da sessão, especialmente em canais de voz onde pacotes de áudio podem chegar depois do evento de finalização.
|
||||
|
||||
### 5. Como ativar/configurar
|
||||
|
||||
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
|
||||
|
||||
### 6. Exemplo
|
||||
|
||||
```text
|
||||
Agente: "Atendimento concluído."
|
||||
→ sessão finalizada
|
||||
|
||||
chega fragmento: "ã..."
|
||||
→ replay "Atendimento concluído."
|
||||
→ nenhum routing / tool / LLM novo
|
||||
```
|
||||
|
||||
### 7. Telemetria e observabilidade
|
||||
|
||||
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
|
||||
|
||||
### 8. Como testar
|
||||
|
||||
1. Crie um teste unitário do comportamento principal.
|
||||
2. Crie um teste de integração do runtime quando houver estado entre turns.
|
||||
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
|
||||
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
|
||||
5. Em produção, valide também telemetria e correlação de IDs.
|
||||
|
||||
### 9. Erros comuns
|
||||
|
||||
- Se o estado terminal não for persistido, outra réplica pode reabrir a jornada.
|
||||
- Não use replay técnico/JSON como fala do cliente.
|
||||
- Essa feature não substitui política de nova sessão intencional.
|
||||
|
||||
### 10. Relação com outras features
|
||||
|
||||
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
|
||||
|
||||
### 11. Referências no repositório
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/channels/interruption.py`
|
||||
- `libs/agent_framework/src/agent_framework/config/settings.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
@@ -0,0 +1,86 @@
|
||||
# Guardrails de Retrieval e Tools
|
||||
|
||||
> Feature do `agent_framework_oci` — guia em Português (PT-BR).
|
||||
|
||||
**Implementação principal:** `guardrails/pipeline.py + guardrails/rails.py`
|
||||
|
||||
---
|
||||
|
||||
### 1. O que é
|
||||
|
||||
Aplica proteção não apenas na mensagem do usuário e na resposta final, mas também no conhecimento recuperado por RAG e nos argumentos/resultados de ferramentas.
|
||||
|
||||
### 2. Problema que resolve
|
||||
|
||||
Em agentes de produção, não é suficiente pedir ao LLM que “faça a coisa certa”. Esta feature move uma responsabilidade específica para uma camada controlada do framework, reduzindo comportamento imprevisível e código duplicado nos agentes de domínio.
|
||||
|
||||
### 3. Fluxo simplificado
|
||||
|
||||
```text
|
||||
Usuário
|
||||
↓
|
||||
Input Guardrails
|
||||
↓
|
||||
RAG → Retrieval Guardrails
|
||||
↓
|
||||
LLM/Tool call → Tool Guardrails
|
||||
↓
|
||||
API
|
||||
↓
|
||||
Output Guardrails
|
||||
```
|
||||
|
||||
### 4. Como funciona internamente
|
||||
|
||||
O framework possui stages distintos de guardrails. Para retrieval, rails como `RAGSEC` e `RET_REL` podem validar segurança e relevância do conteúdo recuperado. Para tools, `TOOL_VAL` valida o uso/argumentos antes ou ao redor da execução.
|
||||
|
||||
As configurações globais incluem `ENABLE_INPUT_GUARDRAILS`, `ENABLE_OUTPUT_GUARDRAILS`, `ENABLE_PARALLEL_GUARDRAILS`, `GUARDRAILS_FAIL_FAST` e `GUARDRAILS_CONFIG_PATH`. O YAML é a fonte de verdade dos rails ativados por agente.
|
||||
|
||||
### 5. Como ativar/configurar
|
||||
|
||||
A ativação exata depende do template/agente. Verifique o arquivo de settings, YAMLs de configuração e o template usado pelo serviço. Nem toda feature precisa de uma flag global: algumas são ativadas pelo contrato retornado por uma tool/workflow.
|
||||
|
||||
### 6. Exemplo
|
||||
|
||||
```yaml
|
||||
retrieval:
|
||||
rails:
|
||||
- RAGSEC
|
||||
- RET_REL
|
||||
|
||||
tool:
|
||||
rails:
|
||||
- TOOL_VAL
|
||||
```
|
||||
|
||||
Exemplo: a pergunta é sobre cancelamento de um serviço, mas o RAG retorna documentação de modem. `RET_REL` pode rejeitar o contexto antes que ele seja usado na resposta.
|
||||
|
||||
### 7. Telemetria e observabilidade
|
||||
|
||||
Quando a feature participa de uma execução de agente, preserve `request_id`, `trace_id`, `session_id`, `agent_id`, `message_id` e demais chaves de correlação no estado/eventos. Isso permite acompanhar a decisão no Langfuse/Observer sem colocar lógica de observabilidade dentro do domínio.
|
||||
|
||||
### 8. Como testar
|
||||
|
||||
1. Crie um teste unitário do comportamento principal.
|
||||
2. Crie um teste de integração do runtime quando houver estado entre turns.
|
||||
3. Verifique o caso feliz e pelo menos um caso de falha/negação.
|
||||
4. Confirme que não há side effects duplicados em retry/replay quando a feature toca transações.
|
||||
5. Em produção, valide também telemetria e correlação de IDs.
|
||||
|
||||
### 9. Erros comuns
|
||||
|
||||
- Ter a implementação do rail não significa que ele está ativo: confira `guardrails.yaml`.
|
||||
- Fail-fast deve ser escolhido conscientemente para cada stage.
|
||||
- Tool guardrail não substitui validação de negócio dentro da própria API/action.
|
||||
|
||||
### 10. Relação com outras features
|
||||
|
||||
Esta feature deve ser usada junto das demais capacidades horizontais do framework, em vez de criar uma implementação paralela no agente de domínio. Em fluxos transacionais, considere especialmente **Clarification**, **Pause/Resume**, **Durable Idempotency**, **Workflow Error Recovery** e **Guardrails**.
|
||||
|
||||
### 11. Referências no repositório
|
||||
|
||||
- `libs/agent_framework/src/agent_framework/guardrails/pipeline.py`
|
||||
- `libs/agent_framework/src/agent_framework/guardrails/rails.py`
|
||||
- `Tuning-Performance/`
|
||||
- `Documentacao/`
|
||||
- `libs/agent_framework/docs/`
|
||||
19
agent_framework_oci/docs/features/pt-BR/README.md
Normal file
19
agent_framework_oci/docs/features/pt-BR/README.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# Feature Guides — Português (PT-BR)
|
||||
|
||||
Documentação das principais features do `agent_framework_oci`.
|
||||
|
||||
- [Autenticação](01_authentication.md)
|
||||
- [Workflow Transacional Determinístico](02_deterministic_transactional_workflow.md)
|
||||
- [Composição por LLM Solicitada pelo Domínio](03_domain_requested_llm_composition.md)
|
||||
- [RAG Solicitado pelo Domínio](04_domain_requested_rag.md)
|
||||
- [Memória de Longo Prazo](05_long_term_memory.md)
|
||||
- [Regressão Offline de Workflow](06_offline_workflow_regression.md)
|
||||
- [Pause](07_pause_resume_workflow.md)
|
||||
- [Aderência de Rota](08_route_stickiness.md)
|
||||
- [Replay em Interrupções de Voz](09_voice_interruption_replay.md)
|
||||
- [Recuperação de Erro em Workflow](10_workflow_error_recovery.md)
|
||||
- [Clarificação](11_clarification.md)
|
||||
- [Idempotência Durável](12_durable_idempotency.md)
|
||||
- [Estados Transacionais Dinâmicos](13_dynamic_transaction_states.md)
|
||||
- [Replay Após Finalização](14_post_finalization_replay.md)
|
||||
- [Guardrails de Retrieval e Tools](15_retrieval_tool_guardrails.md)
|
||||
Reference in New Issue
Block a user